LSSTApplications  10.0-2-g4f67435,11.0.rc2+1,11.0.rc2+12,11.0.rc2+3,11.0.rc2+4,11.0.rc2+5,11.0.rc2+6,11.0.rc2+7,11.0.rc2+8
LSSTDataManagementBasePackage
Background.h
Go to the documentation of this file.
1 // -*- LSST-C++ -*-
2 
3 /*
4  * LSST Data Management System
5  * Copyright 2008-2015 AURA/LSST.
6  *
7  * This product includes software developed by the
8  * LSST Project (http://www.lsst.org/).
9  *
10  * This program is free software: you can redistribute it and/or modify
11  * it under the terms of the GNU General Public License as published by
12  * the Free Software Foundation, either version 3 of the License, or
13  * (at your option) any later version.
14  *
15  * This program is distributed in the hope that it will be useful,
16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18  * GNU General Public License for more details.
19  *
20  * You should have received a copy of the LSST License Statement and
21  * the GNU General Public License along with this program. If not,
22  * see <https://www.lsstcorp.org/LegalNotices/>.
23  */
24 
25 #if !defined(LSST_AFW_MATH_BACKGROUND_H)
26 #define LSST_AFW_MATH_BACKGROUND_H
27 
32 #include <boost/preprocessor/seq.hpp>
33 #include "boost/shared_ptr.hpp"
34 #include "lsst/daf/base/Citizen.h"
35 #include "lsst/pex/exceptions.h"
36 #include "lsst/afw/geom/Box.h"
40 
41 namespace lsst {
42 namespace afw {
43 namespace math {
44 
45 //
46 // Remember to update stringToUndersampleStyle if you change this.
47 // If this happens often, we can play CPP games to put the definition in exactly one place, although swig
48 // may not be happy (so we could think m4 thoughts instead)
49 //
54 };
55 UndersampleStyle stringToUndersampleStyle(std::string const &style);
56 
62 public:
64  int const nxSample,
65  int const nySample,
66  StatisticsControl const sctrl = StatisticsControl(),
67  Property const prop = MEANCLIP,
68  ApproximateControl const actrl =
70  )
71  : _style(Interpolate::AKIMA_SPLINE),
72  _nxSample(nxSample), _nySample(nySample),
74  _sctrl(new StatisticsControl(sctrl)),
75  _prop(prop),
76  _actrl(new ApproximateControl(actrl)) {
77  if (nxSample <= 0 || nySample <= 0) {
78  throw LSST_EXCEPT(lsst::pex::exceptions::LengthError,
79  str(boost::format("You must specify at least one point, not %dx%d")
80  % nxSample % nySample)
81  );
82  }
83  }
84 
89  int const nxSample,
90  int const nySample,
91  StatisticsControl const &sctrl,
92  std::string const &prop,
93  ApproximateControl const actrl =
95  )
96  : _style(Interpolate::AKIMA_SPLINE),
97  _nxSample(nxSample), _nySample(nySample),
99  _sctrl(new StatisticsControl(sctrl)),
101  _actrl(new ApproximateControl(actrl)) {
102  if (nxSample <= 0 || nySample <= 0) {
103  throw LSST_EXCEPT(lsst::pex::exceptions::LengthError,
104  str(boost::format("You must specify at least one point, not %dx%d")
105  % nxSample % nySample)
106  );
107  }
108  }
109  // And now the two old APIs (preserved for backward compatibility)
114  Interpolate::Style const style,
115  int const nxSample = 10,
116  int const nySample = 10,
117  UndersampleStyle const undersampleStyle = THROW_EXCEPTION,
118  StatisticsControl const sctrl = StatisticsControl(),
119  Property const prop = MEANCLIP,
120  ApproximateControl const actrl =
122 
123  )
124  : _style(style),
125  _nxSample(nxSample), _nySample(nySample),
126  _undersampleStyle(undersampleStyle),
127  _sctrl(new StatisticsControl(sctrl)),
128  _prop(prop),
129  _actrl(new ApproximateControl(actrl)) {
130  if (nxSample <= 0 || nySample <= 0) {
131  throw LSST_EXCEPT(lsst::pex::exceptions::LengthError,
132  str(boost::format("You must specify at least one point, not %dx%d")
133  % nxSample % nySample)
134  );
135  }
136  }
137 
144  std::string const &style,
145  int const nxSample = 10,
146  int const nySample = 10,
147  std::string const &undersampleStyle = "THROW_EXCEPTION",
148  StatisticsControl const sctrl = StatisticsControl(),
149  std::string const &prop = "MEANCLIP",
150  ApproximateControl const actrl =
152  )
153  : _style(math::stringToInterpStyle(style)),
154  _nxSample(nxSample), _nySample(nySample),
155  _undersampleStyle(math::stringToUndersampleStyle(undersampleStyle)),
156  _sctrl(new StatisticsControl(sctrl)),
158  _actrl(new ApproximateControl(actrl)) {
159  if (nxSample <= 0 || nySample <= 0) {
160  throw LSST_EXCEPT(lsst::pex::exceptions::LengthError,
161  str(boost::format("You must specify at least one point, not %dx%d")
162  % nxSample % nySample)
163  );
164  }
165  }
166 
167  virtual ~BackgroundControl() {}
168  void setNxSample (int nxSample) {
169  if (nxSample <= 0) {
170  throw LSST_EXCEPT(lsst::pex::exceptions::LengthError,
171  str(boost::format("nxSample must be position, not %d") % nxSample));
172  }
173  _nxSample = nxSample;
174  }
175  void setNySample (int nySample) {
176  if (nySample <= 0) {
177  throw LSST_EXCEPT(lsst::pex::exceptions::LengthError,
178  str(boost::format("nySample must be position, not %d") % nySample));
179  }
180  _nySample = nySample;
181  }
182 
183  void setInterpStyle (Interpolate::Style const style) { _style = style; }
184  // overload to take a string
185  void setInterpStyle (std::string const &style) { _style = math::stringToInterpStyle(style); }
186 
187  void setUndersampleStyle (UndersampleStyle const undersampleStyle) {
188  _undersampleStyle = undersampleStyle;
189  }
190  // overload to take a string
191  void setUndersampleStyle (std::string const &undersampleStyle) {
193  }
194 
195  int getNxSample() const { return _nxSample; }
196  int getNySample() const { return _nySample; }
198  if (_style < 0 || _style >= Interpolate::NUM_STYLES) {
199  throw LSST_EXCEPT(lsst::pex::exceptions::InvalidParameterError,
200  str(boost::format("Style %d is invalid") % _style));
201 
202  }
203  return _style;
204  }
208 
210  void setStatisticsProperty(Property prop) { _prop = prop; }
211  void setStatisticsProperty(std::string prop) { _prop = stringToStatisticsProperty(prop); }
212 
216 
217 private:
218  Interpolate::Style _style; // style of interpolation to use
219  int _nxSample; // number of grid squares to divide image into to sample in x
220  int _nySample; // number of grid squares to divide image into to sample in y
221  UndersampleStyle _undersampleStyle; // what to do when nx,ny are too small for the requested interp style
222  PTR(StatisticsControl) _sctrl; // statistics control object
223  Property _prop; // statistics Property
224  PTR(ApproximateControl) _actrl; // approximate control object
225 };
226 
231 class Background : public daf::base::Citizen {
232 protected:
233  template<typename ImageT>
234  explicit Background(ImageT const& img, BackgroundControl const& bgCtrl);
235 
236  explicit Background(geom::Box2I const imageBBox, int const nx, int const ny);
238  virtual ~Background() { }
239 public:
240  typedef float InternalPixelT;
241 
243  virtual void operator+=(float const delta) = 0;
245  virtual void operator-=(float const delta) = 0;
251  template<typename PixelT>
253  Interpolate::Style const interpStyle,
254  UndersampleStyle const undersampleStyle=THROW_EXCEPTION
255  ) const {
256  return getImage<PixelT>(_imgBBox, interpStyle, undersampleStyle);
257  }
263  template<typename PixelT>
265  std::string const &interpStyle,
266  std::string const &undersampleStyle="THROW_EXCEPTION"
267  ) const {
268  return getImage<PixelT>(math::stringToInterpStyle(interpStyle),
269  stringToUndersampleStyle(undersampleStyle));
270  }
271  template<typename PixelT>
273  lsst::afw::geom::Box2I const& bbox,
274  Interpolate::Style const interpStyle,
275  UndersampleStyle const undersampleStyle=THROW_EXCEPTION
276  ) const {
277  return _getImage(bbox, interpStyle, undersampleStyle, static_cast<PixelT>(0));
278  }
279  template<typename PixelT>
281  lsst::afw::geom::Box2I const& bbox,
282  std::string const& interpStyle,
283  std::string const& undersampleStyle="THROW_EXCEPTION"
284  ) const {
285  return _getImage(bbox, math::stringToInterpStyle(interpStyle),
286  stringToUndersampleStyle(undersampleStyle), static_cast<PixelT>(0));
287  }
288 
293  template<typename PixelT>
295  return getImage<PixelT>(_bctrl->getInterpStyle(), _bctrl->getUndersampleStyle());
296  }
303  return _asUsedInterpStyle;
304  }
309  return _asUsedUndersampleStyle;
310  }
315  ApproximateControl const& actrl,
316  UndersampleStyle const undersampleStyle=THROW_EXCEPTION
317  ) const {
318  InternalPixelT disambiguate = 0;
319  return _getApproximate(actrl, undersampleStyle, disambiguate);
320  }
324  geom::Box2I getImageBBox() const { return _imgBBox; }
325 
326  PTR(BackgroundControl) getBackgroundControl() { return _bctrl; }
327  CONST_PTR(BackgroundControl) getBackgroundControl() const { return _bctrl; }
328 
329 protected:
332  mutable Interpolate::Style _asUsedInterpStyle;
333  mutable UndersampleStyle _asUsedUndersampleStyle;
334 
335  std::vector<double> _xcen;
336  std::vector<double> _ycen;
337  std::vector<int> _xorig;
338  std::vector<int> _yorig;
339  std::vector<int> _xsize;
340  std::vector<int> _ysize;
341  /*
342  * We want getImage to be present in the base class, but a templated virtual function
343  * is impossible. So we'll solve the dilemma with a hack: explicitly defined
344  * virtual functions for the image types we need
345  */
346 #if !defined(SWIG)
347 // We'll evaluate LSST_makeBackground_get{Approximation,Image} for each type in
348 // LSST_makeBackground_get{Approximation,Image}_types,
349 // setting v to the second arg (i.e. "= 0" for the first invocation). The first agument, m, is ignores
350 
351 // Desired types
352 #define LSST_makeBackground_getImage_types (Background::InternalPixelT)
353 #define LSST_makeBackground_getApproximate_types (Background::InternalPixelT)
354 #define LSST_makeBackground_getImage(m, v, T) \
355  virtual PTR(lsst::afw::image::Image<T>) _getImage( \
356  lsst::afw::geom::Box2I const& bbox, \
357  Interpolate::Style const interpStyle, /* Style of the interpolation */ \
358  UndersampleStyle const undersampleStyle=THROW_EXCEPTION, /* Behaviour if there are too few points */\
359  T = 0 /* disambiguate */ \
360  ) const v;
361 
362 #define LSST_makeBackground_getApproximate(m, v, T) \
363  virtual PTR(Approximate<T>) _getApproximate( \
364  ApproximateControl const& actrl, /* Approximation style */ \
365  UndersampleStyle const undersampleStyle=THROW_EXCEPTION, /* Behaviour if there are too few points */\
366  T = 0 /* disambiguate */ \
367  ) const v;
368 
371 #endif
372 private:
373  Background(Background const&);
374  Background& operator=(Background const&);
375  void _setCenOrigSize(int const width, int const height, int const nxSample, int const nySample);
376 };
377 
403 class BackgroundMI : public Background {
404 public:
405  template<typename ImageT>
406  explicit BackgroundMI(ImageT const& img,
407  BackgroundControl const& bgCtrl);
408  explicit BackgroundMI(geom::Box2I const imageDimensions,
409  image::MaskedImage<InternalPixelT> const& statsImage);
410 
411  virtual void operator+=(float const delta);
412  virtual void operator-=(float const delta);
413 
414 
415  double getPixel(Interpolate::Style const style, int const x, int const y) const;
423  double getPixel(int const x, int const y) const {
424  return getPixel(_bctrl->getInterpStyle(), x, y);
425  }
430  return _statsImage;
431  }
432 
433 private:
434  lsst::afw::image::MaskedImage<InternalPixelT> _statsImage; // statistical properties for the grid of subimages
435  mutable std::vector<std::vector<double> > _gridColumns; // interpolated columns for the bicubic spline
436 
437  void _setGridColumns(Interpolate::Style const interpStyle,
438  UndersampleStyle const undersampleStyle,
439  int const iX, std::vector<int> const& ypix) const;
440 
441 #if !defined(SWIG) && defined(LSST_makeBackground_getImage)
444 #if 0 // keep for use in Background instantiations
445 #undef LSST_makeBackground_getImage_types
446 #undef LSST_makeBackground_getApproximate_types
447 #endif
448 #undef LSST_makeBackground_getImage
449 #undef LSST_makeBackground_getApproximate
450 #endif
451  // Here's the worker function for _getImage (non-virtual; it's templated in BackgroundMI, not Background)
452  template<typename PixelT>
453  PTR(image::Image<PixelT>) doGetImage(geom::Box2I const& bbox,
454  Interpolate::Style const interpStyle_,
455  UndersampleStyle const undersampleStyle) const;
456  // and for _getApproximate
457  template<typename PixelT>
458  PTR(Approximate<PixelT>) doGetApproximate(ApproximateControl const& actrl,
459  UndersampleStyle const undersampleStyle) const;
460 };
466 template<typename ImageT>
467 PTR(Background) makeBackground(ImageT const& img, BackgroundControl const& bgCtrl) {
468  return PTR(Background)(new BackgroundMI(img, bgCtrl));
469 }
470 
471 }}} // lsst::afw::math
472 
473 #endif // LSST_AFW_MATH_BACKGROUND_H
int y
Interpolate::Style getInterpStyle() const
Definition: Background.h:197
UndersampleStyle stringToUndersampleStyle(std::string const &style)
Conversion function to switch a string to an UndersampleStyle.
Definition: Background.cc:148
boost::shared_ptr< Background > makeBackground(ImageT const &img, BackgroundControl const &bgCtrl)
A convenience function that uses function overloading to make the correct type of Background...
Definition: Background.h:467
Interpolate::Style stringToInterpStyle(std::string const &style)
Conversion function to switch a string to an Interpolate::Style.
Definition: Interpolate.cc:262
Interpolate values for a set of x,y vector&lt;&gt;s.
Definition: Interpolate.h:37
void setInterpStyle(Interpolate::Style const style)
Definition: Background.h:183
#define PTR(...)
Definition: base.h:41
estimate sample N-sigma clipped mean (N set in StatisticsControl, default=3)
Definition: Statistics.h:72
void setUndersampleStyle(std::string const &undersampleStyle)
Definition: Background.h:191
void setNxSample(int nxSample)
Definition: Background.h:168
BackgroundControl(int const nxSample, int const nySample, StatisticsControl const sctrl=StatisticsControl(), Property const prop=MEANCLIP, ApproximateControl const actrl=ApproximateControl(ApproximateControl::UNKNOWN, 1))
Definition: Background.h:63
#define CONST_PTR(...)
Definition: base.h:47
double getPixel(int const x, int const y) const
Return the background value at a point.
Definition: Background.h:423
UndersampleStyle getUndersampleStyle() const
Definition: Background.h:205
#define LSST_makeBackground_getApproximate_types
Definition: Background.h:353
boost::shared_ptr< StatisticsControl > getStatisticsControl()
Definition: Background.h:206
Extent< double, N > & operator+=(Extent< double, N > &lhs, Extent< int, N > const &rhs)
Definition: Extent.h:429
void setStatisticsProperty(Property prop)
Definition: Background.h:210
Extent< double, N > & operator-=(Extent< double, N > &lhs, Extent< int, N > const &rhs)
Definition: Extent.h:439
UndersampleStyle _undersampleStyle
Definition: Background.h:221
Pass parameters to a Background object.
Definition: Background.h:61
Approximate values for a MaskedImage.
Definition: Approximate.h:38
A virtual base class to evaluate image background levels.
Definition: Background.h:231
An integer coordinate rectangle.
Definition: Box.h:53
float InternalPixelT
type used for any internal images, and returned by getApproximate
Definition: Background.h:240
Control how to make an approximation.
Definition: Approximate.h:47
Pass parameters to a Statistics objectA class to pass parameters which control how the stats are calc...
Definition: Statistics.h:92
boost::shared_ptr< ApproximateControl > getApproximateControl()
Definition: Background.h:214
boost::shared_ptr< ApproximateControl > _actrl
Definition: Background.h:224
void setUndersampleStyle(UndersampleStyle const undersampleStyle)
Definition: Background.h:187
void setApproximateControl(boost::shared_ptr< ApproximateControl > actrl)
Definition: Background.h:213
void setStatisticsProperty(std::string prop)
Definition: Background.h:211
Property getStatisticsProperty() const
Definition: Background.h:209
geom::Box2I _imgBBox
size and origin of input image
Definition: Background.h:330
lsst::afw::image::MaskedImage< InternalPixelT > _statsImage
Definition: Background.h:434
void setNySample(int nySample)
Definition: Background.h:175
#define LSST_makeBackground_getImage_types
Definition: Background.h:352
UndersampleStyle getAsUsedUndersampleStyle() const
Definition: Background.h:308
BackgroundControl(std::string const &style, int const nxSample=10, int const nySample=10, std::string const &undersampleStyle="THROW_EXCEPTION", StatisticsControl const sctrl=StatisticsControl(), std::string const &prop="MEANCLIP", ApproximateControl const actrl=ApproximateControl(ApproximateControl::UNKNOWN, 1))
Definition: Background.h:143
#define LSST_makeBackground_getImage(m, v, T)
Definition: Background.h:354
int x
lsst::afw::image::MaskedImage< InternalPixelT > getStatsImage() const
Return the image of statistical quantities extracted from the image.
Definition: Background.h:429
virtual ~Background()
dtor
Definition: Background.h:238
#define LSST_EXCEPT(type,...)
Definition: Exception.h:46
BackgroundControl(Interpolate::Style const style, int const nxSample=10, int const nySample=10, UndersampleStyle const undersampleStyle=THROW_EXCEPTION, StatisticsControl const sctrl=StatisticsControl(), Property const prop=MEANCLIP, ApproximateControl const actrl=ApproximateControl(ApproximateControl::UNKNOWN, 1))
Definition: Background.h:113
Compute Image Statistics.
Property stringToStatisticsProperty(std::string const property)
Conversion function to switch a string to a Property (see Statistics.h)
Definition: Statistics.cc:715
#define LSST_makeBackground_getApproximate(m, v, T)
Definition: Background.h:362
A class to evaluate image background levels.
Definition: Background.h:403
void setInterpStyle(std::string const &style)
Definition: Background.h:185
std::vector< std::vector< double > > _gridColumns
Definition: Background.h:435
Property
control what is calculated
Definition: Statistics.h:63
geom::Box2I getImageBBox() const
Definition: Background.h:324
boost::shared_ptr< StatisticsControl > _sctrl
Definition: Background.h:222
Include files required for standard LSST Exception handling.
BackgroundControl(int const nxSample, int const nySample, StatisticsControl const &sctrl, std::string const &prop, ApproximateControl const actrl=ApproximateControl(ApproximateControl::UNKNOWN, 1))
Definition: Background.h:88
Interpolate::Style getAsUsedInterpStyle() const
Definition: Background.h:302