casacore
ImageStatistics.h
Go to the documentation of this file.
1 //# ImageStatistics.h: generate statistics from an image
2 //# Copyright (C) 1996,1997,1998,1999,2000,2001,2003
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 //# $Id$
27 
28 #ifndef IMAGES_IMAGESTATISTICS_H
29 #define IMAGES_IMAGESTATISTICS_H
30 
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
34 #include <casacore/casa/BasicSL/String.h>
35 #include <casacore/casa/Utilities/DataType.h>
36 #include <casacore/casa/Logging/LogIO.h>
37 #include <casacore/lattices/LatticeMath/LatticeStatistics.h>
38 #include <casacore/scimath/Mathematics/NumericTraits.h>
39 #include <casacore/casa/iosstrfwd.h>
40 
41 namespace casacore { //# NAMESPACE CASACORE - BEGIN
42 
43 //# Forward Declarations
44 template <class T> class ImageInterface;
45 class IPosition;
46 
47 // <summary>
48 // Displays various statistics from an image.
49 // </summary>
50 
51 // <use visibility=export>
52 
53 // <reviewed reviewer="" date="yyyy/mm/dd" tests="" demos="">
54 // </reviewed>
55 
56 // <prerequisite>
57 // <li> <linkto class=LatticeStatistics>LatticeStatistics</linkto> (base class)
58 // <li> <linkto class=ImageInterface>ImageInterface</linkto>
59 // </prerequisite>
60 
61 // <etymology>
62 // This is a class designed to display and retrieve statistics from images
63 // </etymology>
64 
65 // <synopsis>
66 // This class enable you to display and/or retrieve statistics evaluated over
67 // specified regions from an image. The dimension of the region is arbitrary, but
68 // the size of each dimension is always the size of the corresponding image axis.
69 // The statistics are displayed as a function of location of the axes not
70 // used to evaluate the statistics over. The axes which you evaluate the statistics
71 // over are called the cursor axes, the others are called the display axes.
72 //
73 // This class is derived from the class LatticeStatistics which does all
74 // the work. This class only adds some extra capability in terms of
75 // logging world (rather than pixel) coordinates and computing the
76 // synthesized beam area, if there is one. There are just a few virtual
77 // functions for you to over-ride. These are rather specialized, they
78 // are not part of a general polymorphic interface, just a way to
79 // separate the Lattice and Image functionality out.
80 //
81 // See LatticeStatistics for details and examples.
82 // </synopsis>
83 //
84 // <motivation>
85 // The generation of statistical information from an image is a basic
86 // and necessary capability.
87 // </motivation>
88 
89 // <todo asof="1996/11/26">
90 // <li> Deal with complex images at least for statistics retrieval if not
91 // plotting.
92 // <li> Retrieve statistics at specified location of display axes
93 // <li> Standard errors on statistical quantities
94 // <li> Median, other more exotic statistics. Life made difficult by
95 // accumulation image approach
96 // </todo>
97 
98 
99 template <class T> class ImageStatistics : public LatticeStatistics<T>
100 {
101 public:
102 
103 // Constructor takes the image and a <src>LogIO</src> object for logging.
104 // You can specify whether you want to see progress meters or not.
105 // You can force the storage image to be disk based, otherwise
106 // the decision for core or disk is taken for you.
107 // If <src>clone</src> is True, the input image will be cloned, so the caller
108 // can make changes to the input image, but the statistics will reflect the
109 // image as it was at construction. If False, a reference to the input image
110 // is used, and so the caller shouldn't make changes to the input image between
111 // construction and calling statistics computation methods, unless it calls setNewImage()
112 // to update the changed image. Obviously, cloning the image impacts performance
113 // and memory usage.
115  LogIO& os,
116  Bool showProgress=True,
117  Bool forceDisk=False,
118  Bool clone=True);
119 
120 // Constructor takes the image only. In the absence of a logger you get no messages.
121 // This includes error messages and potential listing of the statistics.
122 // You can specify whether you want to see progress meters or not.
123 // You can force the storage image to be disk based, otherwise
124 // the decision for core or disk is taken for you.
126  Bool showProgress=True,
127  Bool forceDisk=False,
128  Bool clone=True);
129 
130 // Copy constructor. Copy semantics are followed. Therefore any storage image
131 // that has already been created for <src>other</src> is copied to <src>*this</src>
133 
134 // Destructor
135  virtual ~ImageStatistics ();
136 
137 // Assignment operator. Deletes any storage image associated with
138 // the object being assigned to and copies any storage image that has
139 // already been created for "other".
141 
142 // Set a new ImageInterface object. A return value of <src>False</src> indicates the
143 // image had an invalid type or that the internal state of the class is bad.
144 // If <src>clone</src> is True, the input image will be cloned, so the caller
145 // can make changes to the input image, but the statistics will reflect the
146 // image as it was at construction. If False, a reference to the input image
147 // is used, and so the caller shouldn't make changes to the input image between
148 // construction and calling statistics computation methods, unless it calls setNewImage()
149 // to update the changed image. Obviously, cloning the image impacts performance
150 // and memory usage.
151  Bool setNewImage (const ImageInterface<T>& image, Bool clone=True);
152 
153  void setPrecision(Int precision);
154 
155  void setBlc(const IPosition& blc);
156 
157  IPosition getBlc() const;
158 
159  Int getPrecision() const;
160 
161  // list robust statistics? Should be called before display()
162  void showRobust(const Bool show);
163 
164  inline void recordMessages(const Bool rm) { _recordMessages = rm; }
165 
166  inline vector<String> getMessages() { return _messages; }
167 
168  inline void clearMessages() { _messages.resize(0); }
169 
170  void setListStats(Bool b) { _listStats = b; }
171 protected:
172 
174 
175  virtual Bool _canDoFlux() const;
176 
177 private:
178 // Data
179 
182  std::shared_ptr<const ImageInterface<T> > _inImPtrMgr;
186  mutable vector<String> _messages;
187 
188 // Virtual functions. See LatticeStatistics for more information
189 // about these, or see the implementation.
190 
191 // Get label for higher order axes
192  virtual void getLabels(String& higherOrder, String& xAxis, const IPosition& dPos) const;
193 
194  // Get beam area in pixels if possible. Return False if the beam area could not be
195  // calculated.
197  Array<Double>& beamArea, String& msg
198  ) const;
199 
200 // List min and max with world coordinates
201  virtual void listMinMax (ostringstream& osMin,
202  ostringstream& osMax,
203  Int oWidth, DataType type);
204 
205 // List the statistics
206  virtual Bool listStats (Bool hasBeam, const IPosition& dPos,
207  const Matrix<AccumType>& ord);
208 
209  virtual void displayStats(
211  AccumType medAbsDevMed, AccumType quartile,
212  AccumType sumSq, AccumType mean, AccumType var,
213  AccumType rms, AccumType sigma, AccumType dMin,
214  AccumType dMax, AccumType q1, AccumType q3
215  );
216 
217 
218  // If <src>isFluxDensity</src> is False, then the computed value is
219  // a flux (ie flux density integrated over a spectral extent)
221  Bool& isFluxDensity, AccumType sum, Double beamAreaInPixels
222  ) const;
223 
225  Array<AccumType>& flux, const Array<AccumType>& npts,
226  const Array<AccumType>& sum
227  );
228 
230  Quantum<AccumType>& flux, AccumType sum, const IPosition& pos,
231  Bool posInLattice
232  );
233  //# Make members of parent class known.
234 protected:
248 public:
258 };
259 
260 //# Declare extern templates for often used types.
261  extern template class ImageStatistics<Float>;
262 
263 
264 } //# NAMESPACE CASACORE - END
265 
266 #ifndef CASACORE_NO_AUTO_TEMPLATES
267 #include <casacore/images/Images/ImageStatistics.tcc>
268 #endif //# CASACORE_NO_AUTO_TEMPLATES
269 #endif
270 
vector< String > getMessages()
Quantum< AccumType > _flux(Bool &isFluxDensity, AccumType sum, Double beamAreaInPixels) const
If isFluxDensity is False, then the computed value is a flux (ie flux density integrated over a spect...
ImageStatistics(const ImageInterface< T > &image, LogIO &os, Bool showProgress=True, Bool forceDisk=False, Bool clone=True)
Constructor takes the image and a LogIO object for logging.
vector< String > _messages
void recordMessages(const Bool rm)
virtual Bool _getBeamArea(Array< Double > &beamArea, String &msg) const
Get beam area in pixels if possible.
ImageStatistics(const ImageStatistics< T > &other)
Copy constructor.
virtual ~ImageStatistics()
Destructor.
virtual void displayStats(AccumType nPts, AccumType sum, AccumType median, AccumType medAbsDevMed, AccumType quartile, AccumType sumSq, AccumType mean, AccumType var, AccumType rms, AccumType sigma, AccumType dMin, AccumType dMax, AccumType q1, AccumType q3)
const ImageInterface< T > * pInImage_p
void setBlc(const IPosition &blc)
virtual Bool listStats(Bool hasBeam, const IPosition &dPos, const Matrix< AccumType > &ord)
List the statistics.
virtual void listMinMax(ostringstream &osMin, ostringstream &osMax, Int oWidth, DataType type)
List min and max with world coordinates.
ImageStatistics(const ImageInterface< T > &image, Bool showProgress=True, Bool forceDisk=False, Bool clone=True)
Constructor takes the image only.
Bool setNewImage(const ImageInterface< T > &image, Bool clone=True)
Set a new ImageInterface object.
virtual Bool _canDoFlux() const
Virtual Functions.
ImageStatistics< T > & operator=(const ImageStatistics< T > &other)
Assignment operator.
void setPrecision(Int precision)
Bool _computeFlux(Quantum< AccumType > &flux, AccumType sum, const IPosition &pos, Bool posInLattice)
Bool _computeFlux(Array< AccumType > &flux, const Array< AccumType > &npts, const Array< AccumType > &sum)
NumericTraits< T >::PrecisionType AccumType
std::shared_ptr< const ImageInterface< T > > _inImPtrMgr
virtual void getLabels(String &higherOrder, String &xAxis, const IPosition &dPos) const
Virtual functions.
IPosition getBlc() const
void showRobust(const Bool show)
list robust statistics? Should be called before display()
Char PrecisionType
Higher precision type (Float->Double)
String: the storage and methods of handling collections of characters.
Definition: String.h:225
this file contains all the compiler specific defines
Definition: mainpage.dox:28
const Bool False
Definition: aipstype.h:44
LatticeExprNode mean(const LatticeExprNode &expr)
LatticeExprNode sum(const LatticeExprNode &expr)
int Int
Definition: aipstype.h:50
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
const Bool True
Definition: aipstype.h:43
double Double
Definition: aipstype.h:55
LatticeExprNode median(const LatticeExprNode &expr)
TableExprNode rms(const TableExprNode &array)
Definition: ExprNode.h:1680