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