Line data    Source code

       1             : //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
       2             : //# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
       3             : //# License for more details.
       4             : //#
       5             : //# You should have received a copy of the GNU Library General Public License
       6             : //# along with this library; if not, write to the Free Software Foundation,
       7             : //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
       8             : //#
       9             : //# Correspondence concerning AIPS++ should be addressed as follows:
      10             : //#        Internet email: casa-feedback@nrao.edu.
      11             : //#        Postal address: AIPS++ Project Office
      12             : //#                        National Radio Astronomy Observatory
      13             : //#                        520 Edgemont Road
      14             : //#                        Charlottesville, VA 22903-2475 USA
      15             : //#
      16             : 
      17             : #ifndef REGIONS_ANNREGION_H
      18             : #define REGIONS_ANNREGION_H
      19             : 
      20             : #include <casacore/coordinates/Coordinates/CoordinateSystem.h>
      21             : #include <imageanalysis/Annotations/AnnotationBase.h>
      22             : #include <casacore/images/Regions/WCBox.h>
      23             : #include <casacore/images/Regions/ImageRegion.h>
      24             : #include <casacore/measures/Measures/MDirection.h>
      25             : #include <casacore/measures/Measures/MFrequency.h>
      26             : #include <casacore/casa/Utilities/CountedPtr.h>
      27             : 
      28             : namespace casa {
      29             : 
      30             : // <summary>
      31             : // This class represents a annotation referring to a region specified in an ascii region file as proposed
      32             : // in CAS-2285
      33             : // </summary>
      34             : // <author>Dave Mehringer</author>
      35             : // <use visibility=export>
      36             : // <reviewed reviewer="" date="yyyy/mm/dd" tests="" demos="">
      37             : // </reviewed>
      38             : // <prerequisite>
      39             : 
      40             : // </prerequisite>
      41             : 
      42             : // <etymology>
      43             : // Holds the specification of an annotation containing a region as specified in ASCII format.
      44             : // </etymology>
      45             : 
      46             : // <synopsis>
      47             : // This class is meant to be a container for all parameters necessary to specify a region per
      48             : // the format proposal attached to CAS-2285 (https://bugs.nrao.edu/browse/CAS-2285).
      49             : 
      50             : // Conversions of frequency from one reference frame to another are done here. The position of
      51             : // the reference pixel in the supplied coordinate system is used when converting frequencies.
      52             : // </synopsis>
      53             : 
      54             : class AnnRegion: public AnnotationBase {
      55             : 
      56             : public:
      57             : 
      58             :         virtual ~AnnRegion();
      59             : 
      60             :         void setAnnotationOnly(const casacore::Bool isAnnotationOnly);
      61             : 
      62             :         // is this region an annotation only? ie just for graphical rendering?
      63             :         casacore::Bool isAnnotationOnly() const;
      64             : 
      65             :         virtual casacore::TableRecord asRecord() const;
      66             : 
      67             :         virtual casacore::ImageRegion asImageRegion() const;
      68             : 
      69             :         // this version is deprecated, use the version that returns
      70             :         // std::shared_ptr instead
      71             :         virtual casacore::CountedPtr<const casacore::WCRegion> getRegion() const;
      72             : 
      73             :         virtual std::shared_ptr<const casacore::WCRegion> getRegion2() const;
      74             : 
      75             :         // returns true unless overridden.
      76             :         virtual casacore::Bool isRegion() const;
      77             : 
      78             :         void setDifference(const casacore::Bool difference);
      79             : 
      80             :         casacore::Bool isDifference() const;
      81             : 
      82             :         // get the pixel range included in the spectral selection.
      83             :         // If there is no spectral axis, a zero length vector is returned. Otherwise,
      84             :         // a vector of two values is returned. The zeroth value will always be less
      85             :         // than or equal to the first.
      86             :     std::vector<casacore::Double> getSpectralPixelRange() const;
      87             : 
      88             : 
      89             :         casacore::Bool setFrequencyLimits(
      90             :                 const casacore::Quantity& beginFreq,
      91             :                 const casacore::Quantity& endFreq,
      92             :                 const casacore::String& freqRefFrame,
      93             :                 const casacore::String& dopplerString,
      94             :                 const casacore::Quantity& restfreq
      95             :         );
      96             : 
      97             : protected:
      98             : 
      99             :         // only to be called by subclasses
     100             : 
     101             :         // beginFreq and endFreq can both be 0, in which case
     102             :         // all the spectral range is used if a spectral axis exists in
     103             :         // <src>csys</csys>. If one of <src>beginFreq</src> or <src>endFreq</src>
     104             :         // is given, the other must be given. Frequency units can either conform
     105             :         // to Hz, m/s, or pix. If <src>beginFreq</src> and <src>endFreq</src> are not
     106             :         // specifed or if they are specified in pixel units,
     107             :         // <src>freqRefFrame</src>, <src>dopplerString</src>, and
     108             :         // <src>restfreq</src> are ignored. If provided, <src>beginFreq</src>
     109             :         // and <src>endFreq</src> must conform to the same units.
     110             :         // <src>requireImageRegion</src> indicates whether to rethrow the
     111             :         // ToLCRegionConversionError exception when the region is outside the
     112             :         // image, or to create the AnnRegion object even if the ImageRegion has no
     113             :         // lattice region. The default (true) rethrows the exception to maintain
     114             :         // the previous behavior.
     115             :         // CAS-12631: added for CARTA, which can import regions outside an image.
     116             :         AnnRegion(
     117             :                 const Type shape,
     118             :                 const casacore::String& dirRefFrameString,
     119             :                 const casacore::CoordinateSystem& csys,
     120             :                 const casacore::IPosition& imShape,
     121             :                 const casacore::Quantity& beginFreq,
     122             :                 const casacore::Quantity& endFreq,
     123             :                 const casacore::String& freqRefFrame,
     124             :                 const casacore::String& dopplerString,
     125             :                 const casacore::Quantity& restfreq,
     126             :                 const casacore::Vector<casacore::Stokes::StokesTypes> stokes,
     127             :                 const casacore::Bool annotationOnly,
     128             :                 casacore::Bool requireImageRegion=true
     129             :         );
     130             : 
     131             :         // use if all coordinate values will be specified in
     132             :         // the same frames as the input coordinate system. frequencies
     133             :         // and the annotationOnly flag can be set after
     134             :         // construction. By default, all frequencies and all polarizations
     135             :         // are used, and the annotationOnly flag is false
     136             :         AnnRegion(
     137             :                 const Type shape,
     138             :                 const casacore::CoordinateSystem& csys,
     139             :                 const casacore::IPosition& imShape,
     140             :                 const casacore::Vector<casacore::Stokes::StokesTypes>& stokes,
     141             :                 casacore::Bool requireImageRegion=true
     142             :         );
     143             : 
     144             :         // copy constructor
     145             :         AnnRegion(const AnnRegion& other);
     146             : 
     147             :         // assignment operator
     148             :         AnnRegion& operator= (const AnnRegion& rhs);
     149             : 
     150             :         casacore::Bool operator== (const AnnRegion& other) const;
     151             : 
     152             :         // check if image region has a region
     153             :         casacore::Bool hasImageRegion() const;
     154             : 
     155             :         // extend the direction plane region over spectral and/or polarization
     156             :         // coordinates
     157             :         void _extend();
     158             : 
     159             :         void _toRecord(const casacore::ImageRegion& region);
     160             : 
     161             :         // convert a length in pixels to an angle.
     162             :         casacore::Quantity _lengthToAngle(
     163             :                 const casacore::Quantity& quantity, const casacore::uInt pixelAxis
     164             :         ) const;
     165             : 
     166             :         virtual void _printPrefix(std::ostream& os) const;
     167             : 
     168             :         // subclasses must call this at construction to set their base region
     169             :         // defined in the direction plane
     170             :         void _setDirectionRegion(const casacore::ImageRegion& region);
     171             : 
     172             :         casacore::Bool _requireImageRegion;
     173             :         casacore::ImageRegion _imageRegion, _directionRegion;
     174             : 
     175             : private:
     176             : 
     177             :         casacore::Bool _isAnnotationOnly;
     178             :         casacore::Bool _isDifference, _constructing;
     179             :         casacore::IPosition _imShape;
     180             :         std::vector<casacore::Double> _spectralPixelRange;
     181             : 
     182             :         static const casacore::String _class;
     183             : 
     184             :         casacore::WCBox _makeExtensionBox(
     185             :                 const casacore::Vector<casacore::Quantity>& freqRange,
     186             :                 const casacore::Vector<casacore::Stokes::StokesTypes>& stokesRange,
     187             :                 const casacore::IPosition& pixelAxes
     188             :         ) const;
     189             : 
     190             :         void _init();
     191             : 
     192             :         casacore::Bool _hasDirectionRegion();
     193             : 
     194             : };
     195             : 
     196             : // Just need a identifable expection class, compiler can generate implementation implicitly
     197             : class ToLCRegionConversionError : public casacore::AipsError {
     198             : public:
     199           0 :         ToLCRegionConversionError(casacore::String msg) : casacore::AipsError(msg) {}
     200             : };
     201             : 
     202             : }
     203             : 
     204             : 
     205             : 
     206             : #endif