GaussianBeam.h

Go to the documentation of this file.

//# Copyright (C) 1996,1997,1998,1999,2000,2001,2003
//# Associated Universities, Inc. Washington DC, USA.
//#
//# This library is free software; you can redistribute it and/or modify it
//# under the terms of the GNU Library General Public License as published by
//# the Free Software Foundation; either version 2 of the License, or (at your
//# option) any later version.
//#
//# This library is distributed in the hope that it will be useful, but WITHOUT
//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
//# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
//# License for more details.
//#
//# You should have received a copy of the GNU Library General Public License
//# along with this library; if not, write to the Free Software Foundation,
//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
//#
//# Correspondence concerning AIPS++ should be addressed as follows:
//#        Internet email: casa-feedback@nrao.edu.
//#        Postal address: AIPS++ Project Office
//#                        National Radio Astronomy Observatory
//#                        520 Edgemont Road
//#                        Charlottesville, VA 22903-2475 USA
 
#ifndef SCIMATH_GAUSSIANBEAM_H
#define SCIMATH_GAUSSIANBEAM_H
 
#include <casacore/casa/aips.h>
#include <casacore/casa/Quanta/Quantum.h>
 
namespace casacore {
 
// <summary>
// Represents a Gaussian restoring beam associated with an image.
// </summary>
 
// <use visibility=export>
 
// <reviewed reviewer="" date="yyyy/mm/dd" tests="" demos="">
// </reviewed>
 
// <prerequisite>
// </prerequisite>
 
// <etymology>
// A Gaussian Beam.
// </etymology>
 
// <synopsis>
// This class represents a Gaussian restoring beam associated with
// a deconvolved image.
// </synopsis>
//
// <example>
 
// </example>
 
 
// <motivation>
// Restoring beams are used many places in image analysis tasks.
// </motivation>
 
// <todo>
// </todo>
 
class GaussianBeam {
public:
 
    static const GaussianBeam NULL_BEAM;
 
    // create a beam with all quantities zero (a null beam).
    GaussianBeam();
 
 
    // Construct a beam from a set of Quantities. If minor > major
    // an exception is thrown. If any units are not angular, an
    // exception is thrown
    GaussianBeam(
        const Quantity& major, const Quantity& minor,
        const Quantity& pa
    );
 
    // Construct a beam from a 3-Vector of Quantities representing
    // the major axis, the minor axis and the position angle (in that order).
    // If parms[1] > parms[0] (minor axis > major axis),
    // an exception is thrown. If any units are not angular, an
    // exception is thrown
    GaussianBeam(
        const Vector<Quantity>& parms
    );
 
    GaussianBeam(const GaussianBeam& other);
 
    ~GaussianBeam();
 
    GaussianBeam& operator=(const GaussianBeam& other);
 
    Bool operator==(const GaussianBeam& other) const;
 
    Bool operator!=(const GaussianBeam& other) const;
 
    // returns the major axis in the same units as it had at construction
    const Quantity& getMajor() const;
 
    // returns the value portion of the major axis in the specified units
    Double getMajor(const Unit& u) const;
 
    // returns the minor axis in the same units as it had at construction
    const Quantity& getMinor() const;
 
    // returns the value portion of the minor axis in the specified units
    Double getMinor(const Unit& u) const;
 
    // returns the position angle's value as it was at construction,
    // unless <src>unwrap</src> is True, in which case the value of the angle
    // returned will be between -90 and 90 degrees (but with unit the same
    // as it had when this object was constructed).
    Quantity getPA(const Bool unwrap=True) const;
 
    // returns the value portion of the position angle in the specified units
    Double getPA(const Unit& u, const Bool unwrap=True) const;
 
    // returns the beam area in the specified <src>unit</src>, which much conform to
    // solid angle units.
    Double getArea(const Unit& unit) const;
 
    // is this object a null beam (ie is either its major and/or minor axis zero)?
    Bool isNull() const;
 
    // returns GassianBeam.
    static const String& className();
 
    Record toRecord() const;
 
    void setMajorMinor(const Quantity& majAx, const Quantity& minAx);
 
    // if unwrap=True, unwrap pa so its value lies in the range
    // -90 to 90 degrees before setting it.
    void setPA(const Quantity& pa, Bool unwrap=False);
 
    static GaussianBeam fromRecord(const Record& rec);
 
    // convert this object to a three-Vector of (major FWHM, minor FWHM, and pa).
    // If <src>unwrap</src> is True, the returned pa will fall between -90 and +90
    // degrees.
    Vector<Quantity> toVector(const Bool unwrap=True) const;
 
    // convert stored Quantities to the specified units
    void convert(const String& majUnit, const String& minUnit,
                     const String& paUnit);
 
protected:
    Quantity _major, _minor, _pa;
 
private:
    static Quantity _unwrap(const Quantity& pa);
 
};
 
 
 
ostream &operator<<(ostream &os, const GaussianBeam& beam);
 
LogIO &operator<<(LogIO &os, const GaussianBeam& beam);
 
Bool near(const GaussianBeam& left, const GaussianBeam& other,
          const Double relWidthTol, const Quantity& absPaTol);
 
} //# end namespace
 
#endif