LSST Applications  21.0.0-147-g0e635eb1+1acddb5be5,22.0.0+052faf71bd,22.0.0+1ea9a8b2b2,22.0.0+6312710a6c,22.0.0+729191ecac,22.0.0+7589c3a021,22.0.0+9f079a9461,22.0.1-1-g7d6de66+b8044ec9de,22.0.1-1-g87000a6+536b1ee016,22.0.1-1-g8e32f31+6312710a6c,22.0.1-10-gd060f87+016f7cdc03,22.0.1-12-g9c3108e+df145f6f68,22.0.1-16-g314fa6d+c825727ab8,22.0.1-19-g93a5c75+d23f2fb6d8,22.0.1-19-gb93eaa13+aab3ef7709,22.0.1-2-g8ef0a89+b8044ec9de,22.0.1-2-g92698f7+9f079a9461,22.0.1-2-ga9b0f51+052faf71bd,22.0.1-2-gac51dbf+052faf71bd,22.0.1-2-gb66926d+6312710a6c,22.0.1-2-gcb770ba+09e3807989,22.0.1-20-g32debb5+b8044ec9de,22.0.1-23-gc2439a9a+fb0756638e,22.0.1-3-g496fd5d+09117f784f,22.0.1-3-g59f966b+1e6ba2c031,22.0.1-3-g849a1b8+f8b568069f,22.0.1-3-gaaec9c0+c5c846a8b1,22.0.1-32-g5ddfab5d3+60ce4897b0,22.0.1-4-g037fbe1+64e601228d,22.0.1-4-g8623105+b8044ec9de,22.0.1-5-g096abc9+d18c45d440,22.0.1-5-g15c806e+57f5c03693,22.0.1-7-gba73697+57f5c03693,master-g6e05de7fdc+c1283a92b8,master-g72cdda8301+729191ecac,w.2021.39
LSST Data Management Base Package
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 /*
28  * Estimate image backgrounds
29  */
30 #include <boost/preprocessor/seq.hpp>
31 #include <memory>
32 #include "lsst/pex/exceptions.h"
33 #include "lsst/geom/Box.h"
37 
38 namespace lsst {
39 namespace afw {
40 namespace math {
41 
42 //
43 // Remember to update stringToUndersampleStyle if you change this.
44 // If this happens often, we can play CPP games to put the definition in exactly one place, although swig
45 // may not be happy (so we could think m4 thoughts instead)
46 //
52 
57 public:
65  BackgroundControl(int const nxSample, int const nySample,
66  StatisticsControl const sctrl = StatisticsControl(), Property const prop = MEANCLIP,
68  : _style(Interpolate::AKIMA_SPLINE),
69  _nxSample(nxSample),
70  _nySample(nySample),
71  _undersampleStyle(THROW_EXCEPTION),
72  _sctrl(new StatisticsControl(sctrl)),
73  _prop(prop),
74  _actrl(new ApproximateControl(actrl)) {
75  if (nxSample <= 0 || nySample <= 0) {
77  str(boost::format("You must specify at least one point, not %dx%d") % nxSample %
78  nySample));
79  }
80  }
81 
91  BackgroundControl(int const nxSample, int const nySample, StatisticsControl const& sctrl,
92  std::string const& prop,
94  : _style(Interpolate::AKIMA_SPLINE),
95  _nxSample(nxSample),
96  _nySample(nySample),
97  _undersampleStyle(THROW_EXCEPTION),
98  _sctrl(new StatisticsControl(sctrl)),
99  _prop(stringToStatisticsProperty(prop)),
100  _actrl(new ApproximateControl(actrl)) {
101  if (nxSample <= 0 || nySample <= 0) {
103  str(boost::format("You must specify at least one point, not %dx%d") % nxSample %
104  nySample));
105  }
106  }
118  BackgroundControl(Interpolate::Style const style, int const nxSample = 10, int const nySample = 10,
119  UndersampleStyle const undersampleStyle = THROW_EXCEPTION,
120  StatisticsControl const sctrl = StatisticsControl(), Property const prop = MEANCLIP,
122 
123  )
124  : _style(style),
125  _nxSample(nxSample),
126  _nySample(nySample),
127  _undersampleStyle(undersampleStyle),
128  _sctrl(new StatisticsControl(sctrl)),
129  _prop(prop),
130  _actrl(new ApproximateControl(actrl)) {
131  if (nxSample <= 0 || nySample <= 0) {
133  str(boost::format("You must specify at least one point, not %dx%d") % nxSample %
134  nySample));
135  }
136  }
137 
149  BackgroundControl(std::string const& style, int const nxSample = 10, int const nySample = 10,
150  std::string const& undersampleStyle = "THROW_EXCEPTION",
151  StatisticsControl const sctrl = StatisticsControl(),
152  std::string const& prop = "MEANCLIP",
154  : _style(math::stringToInterpStyle(style)),
155  _nxSample(nxSample),
156  _nySample(nySample),
157  _undersampleStyle(math::stringToUndersampleStyle(undersampleStyle)),
158  _sctrl(new StatisticsControl(sctrl)),
159  _prop(stringToStatisticsProperty(prop)),
160  _actrl(new ApproximateControl(actrl)) {
161  if (nxSample <= 0 || nySample <= 0) {
163  str(boost::format("You must specify at least one point, not %dx%d") % nxSample %
164  nySample));
165  }
166  }
167 
172 
173  virtual ~BackgroundControl() = default;
174  void setNxSample(int nxSample) {
175  if (nxSample <= 0) {
177  str(boost::format("nxSample must be position, not %d") % nxSample));
178  }
179  _nxSample = nxSample;
180  }
181  void setNySample(int nySample) {
182  if (nySample <= 0) {
184  str(boost::format("nySample must be position, not %d") % nySample));
185  }
186  _nySample = nySample;
187  }
188 
189  void setInterpStyle(Interpolate::Style const style) { _style = style; }
190  // overload to take a string
191  void setInterpStyle(std::string const& style) { _style = math::stringToInterpStyle(style); }
192 
193  void setUndersampleStyle(UndersampleStyle const undersampleStyle) {
194  _undersampleStyle = undersampleStyle;
195  }
196  // overload to take a string
197  void setUndersampleStyle(std::string const& undersampleStyle) {
198  _undersampleStyle = math::stringToUndersampleStyle(undersampleStyle);
199  }
200 
201  int getNxSample() const { return _nxSample; }
202  int getNySample() const { return _nySample; }
204  if (_style < 0 || _style >= Interpolate::NUM_STYLES) {
206  str(boost::format("Style %d is invalid") % _style));
207  }
208  return _style;
209  }
210  UndersampleStyle getUndersampleStyle() const { return _undersampleStyle; }
213 
214  Property getStatisticsProperty() const { return _prop; }
215  void setStatisticsProperty(Property prop) { _prop = prop; }
217 
221 
222 private:
223  Interpolate::Style _style; // style of interpolation to use
224  int _nxSample; // number of grid squares to divide image into to sample in x
225  int _nySample; // number of grid squares to divide image into to sample in y
226  UndersampleStyle _undersampleStyle; // what to do when nx,ny are too small for the requested interp style
227  std::shared_ptr<StatisticsControl> _sctrl; // statistics control object
228  Property _prop; // statistics Property
229  std::shared_ptr<ApproximateControl> _actrl; // approximate control object
230 };
231 
235 class Background {
236 protected:
246  template <typename ImageT>
247  explicit Background(ImageT const& img, BackgroundControl const& bgCtrl);
248 
259  explicit Background(lsst::geom::Box2I const imageBBox, int const nx, int const ny);
260 
261 public:
262  using InternalPixelT = float;
263 
264  Background(Background const&) = delete;
265  Background(Background&&) = delete;
267  virtual ~Background() = default;
268  Background& operator=(Background const&) = delete;
270 
272  virtual Background& operator+=(float const delta) = 0;
274  virtual Background& operator-=(float const delta) = 0;
282  template <typename PixelT>
284  Interpolate::Style const interpStyle,
285  UndersampleStyle const undersampleStyle = THROW_EXCEPTION) const {
286  return getImage<PixelT>(_imgBBox, interpStyle, undersampleStyle);
287  }
295  template <typename PixelT>
297  std::string const& interpStyle, std::string const& undersampleStyle = "THROW_EXCEPTION") const {
298  return getImage<PixelT>(math::stringToInterpStyle(interpStyle),
299  stringToUndersampleStyle(undersampleStyle));
300  }
306  template <typename PixelT>
308  lsst::geom::Box2I const& bbox, Interpolate::Style const interpStyle,
309  UndersampleStyle const undersampleStyle = THROW_EXCEPTION) const {
310  return _getImage(bbox, interpStyle, undersampleStyle, static_cast<PixelT>(0));
311  }
317  template <typename PixelT>
319  lsst::geom::Box2I const& bbox, std::string const& interpStyle,
320  std::string const& undersampleStyle = "THROW_EXCEPTION") const {
321  return _getImage(bbox, math::stringToInterpStyle(interpStyle),
322  stringToUndersampleStyle(undersampleStyle), static_cast<PixelT>(0));
323  }
324 
328  template <typename PixelT>
330  return getImage<PixelT>(_bctrl->getInterpStyle(), _bctrl->getUndersampleStyle());
331  }
349  ApproximateControl const& actrl,
350  UndersampleStyle const undersampleStyle = THROW_EXCEPTION) const {
351  InternalPixelT disambiguate = 0;
352  return _getApproximate(actrl, undersampleStyle, disambiguate);
353  }
358 
361 
362 protected:
367 
374  /*
375  * We want getImage to be present in the base class, but a templated virtual function
376  * is impossible. So we'll solve the dilemma with a hack: explicitly defined
377  * virtual functions for the image types we need
378  */
379 // We'll evaluate LSST_makeBackground_get{Approximation,Image} for each type in
380 // LSST_makeBackground_get{Approximation,Image}_types,
381 // setting v to the second arg (i.e. "= 0" for the first invocation). The first agument, m, is ignores
382 
383 // Desired types
384 #define LSST_makeBackground_getImage_types (Background::InternalPixelT)
385 #define LSST_makeBackground_getApproximate_types (Background::InternalPixelT)
386 #define LSST_makeBackground_getImage(m, v, T) \
387  virtual std::shared_ptr<lsst::afw::image::Image<T>> _getImage( \
388  lsst::geom::Box2I const& bbox, \
389  Interpolate::Style const interpStyle, /* Style of the interpolation */ \
390  UndersampleStyle const undersampleStyle = \
391  THROW_EXCEPTION, /* Behaviour if there are too few points */ \
392  T = 0 /* disambiguate */ \
393  ) const v;
394 
395 #define LSST_makeBackground_getApproximate(m, v, T) \
396  virtual std::shared_ptr<Approximate<T>> _getApproximate( \
397  ApproximateControl const& actrl, /* Approximation style */ \
398  UndersampleStyle const undersampleStyle = \
399  THROW_EXCEPTION, /* Behaviour if there are too few points */ \
400  T = 0 /* disambiguate */ \
401  ) const v;
402 
405 private:
410  void _setCenOrigSize(int const width, int const height, int const nxSample, int const nySample);
411 };
412 
434 class BackgroundMI : public Background {
435 public:
436  template <typename ImageT>
458  explicit BackgroundMI(ImageT const& img, BackgroundControl const& bgCtrl);
465  explicit BackgroundMI(lsst::geom::Box2I const imageDimensions,
466  image::MaskedImage<InternalPixelT> const& statsImage);
467 
468  BackgroundMI(BackgroundMI const&) = delete;
472  ~BackgroundMI() override = default;
473 
479  BackgroundMI& operator+=(float const delta) override;
485  BackgroundMI& operator-=(float const delta) override;
486 
491 
492 private:
494  _statsImage; // statistical properties for the grid of subimages
495  mutable std::vector<std::vector<double>> _gridColumns; // interpolated columns for the bicubic spline
496 
497  void _setGridColumns(Interpolate::Style const interpStyle, UndersampleStyle const undersampleStyle,
498  int const iX, std::vector<int> const& ypix) const;
499 
500 #if defined(LSST_makeBackground_getImage)
501  BOOST_PP_SEQ_FOR_EACH(LSST_makeBackground_getImage, override, LSST_makeBackground_getImage_types);
502  BOOST_PP_SEQ_FOR_EACH(LSST_makeBackground_getApproximate, override,
504 #undef LSST_makeBackground_getImage
505 #undef LSST_makeBackground_getApproximate
506 #endif
507  // Here's the worker function for _getImage (non-virtual; it's templated in BackgroundMI, not Background)
511  template <typename PixelT>
513  Interpolate::Style const interpStyle_,
514  UndersampleStyle const undersampleStyle) const;
515  // and for _getApproximate
516  template <typename PixelT>
517  std::shared_ptr<Approximate<PixelT>> doGetApproximate(ApproximateControl const& actrl,
518  UndersampleStyle const undersampleStyle) const;
519 };
525 template <typename ImageT>
527  return std::shared_ptr<Background>(new BackgroundMI(img, bgCtrl));
528 }
529 } // namespace math
530 } // namespace afw
531 } // namespace lsst
532 
533 #endif // LSST_AFW_MATH_BACKGROUND_H
AmpInfoBoxKey bbox
Definition: Amplifier.cc:117
#define LSST_makeBackground_getImage(m, v, T)
Definition: Background.h:386
#define LSST_makeBackground_getApproximate(m, v, T)
Definition: Background.h:395
#define LSST_makeBackground_getApproximate_types
Definition: Background.h:385
#define LSST_makeBackground_getImage_types
Definition: Background.h:384
#define LSST_EXCEPT(type,...)
Create an exception with a given type.
Definition: Exception.h:48
Control how to make an approximation.
Definition: Approximate.h:48
Pass parameters to a Background object.
Definition: Background.h:56
std::shared_ptr< ApproximateControl > getApproximateControl()
Definition: Background.h:219
void setNySample(int nySample)
Definition: Background.h:181
void setNxSample(int nxSample)
Definition: Background.h:174
void setApproximateControl(std::shared_ptr< ApproximateControl > actrl)
Definition: Background.h:218
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))
Overload constructor to handle strings for both interp and undersample styles.
Definition: Background.h:149
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))
Overload constructor to provide interp style.
Definition: Background.h:118
BackgroundControl(BackgroundControl const &)=default
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:65
std::shared_ptr< StatisticsControl const > getStatisticsControl() const
Definition: Background.h:212
virtual ~BackgroundControl()=default
BackgroundControl & operator=(BackgroundControl const &)=default
BackgroundControl(BackgroundControl &&)=default
Interpolate::Style getInterpStyle() const
Definition: Background.h:203
void setInterpStyle(Interpolate::Style const style)
Definition: Background.h:189
BackgroundControl & operator=(BackgroundControl &&)=default
void setUndersampleStyle(UndersampleStyle const undersampleStyle)
Definition: Background.h:193
BackgroundControl(int const nxSample, int const nySample, StatisticsControl const &sctrl, std::string const &prop, ApproximateControl const actrl=ApproximateControl(ApproximateControl::UNKNOWN, 1))
Overload constructor to handle string for statistical operator.
Definition: Background.h:91
void setStatisticsProperty(Property prop)
Definition: Background.h:215
void setStatisticsProperty(std::string prop)
Definition: Background.h:216
std::shared_ptr< StatisticsControl > getStatisticsControl()
Definition: Background.h:211
UndersampleStyle getUndersampleStyle() const
Definition: Background.h:210
void setUndersampleStyle(std::string const &undersampleStyle)
Definition: Background.h:197
Property getStatisticsProperty() const
Definition: Background.h:214
void setInterpStyle(std::string const &style)
Definition: Background.h:191
std::shared_ptr< ApproximateControl const > getApproximateControl() const
Definition: Background.h:220
A virtual base class to evaluate image background levels.
Definition: Background.h:235
std::vector< double > _ycen
y center ...
Definition: Background.h:369
std::vector< double > _xcen
x center pix coords of sub images
Definition: Background.h:368
UndersampleStyle getAsUsedUndersampleStyle() const
Return the UndersampleStyle that we actually used in the last call to getImage()
Definition: Background.h:341
virtual Background & operator+=(float const delta)=0
Add a constant level to a background.
Interpolate::Style getAsUsedInterpStyle() const
Return the Interpolate::Style that we actually used in the last call to getImage()
Definition: Background.h:337
Background(Background &&)=delete
Background(Background const &)=delete
lsst::geom::Box2I getImageBBox() const
Return the input image's (PARENT) bounding box.
Definition: Background.h:357
Background(ImageT const &img, BackgroundControl const &bgCtrl)
Constructor for Background.
Definition: Background.cc:44
Background & operator=(Background const &)=delete
std::shared_ptr< BackgroundControl > getBackgroundControl()
Definition: Background.h:359
std::shared_ptr< BackgroundControl const > getBackgroundControl() const
Definition: Background.h:360
std::shared_ptr< lsst::afw::image::Image< PixelT > > getImage(lsst::geom::Box2I const &bbox, Interpolate::Style const interpStyle, UndersampleStyle const undersampleStyle=THROW_EXCEPTION) const
Definition: Background.h:307
std::vector< int > _xsize
x size of sub images
Definition: Background.h:372
lsst::geom::Box2I _imgBBox
size and origin of input image
Definition: Background.h:363
std::vector< int > _xorig
x origin pix coords of sub images
Definition: Background.h:370
virtual Background & operator-=(float const delta)=0
Subtract a constant level from a background.
std::shared_ptr< lsst::afw::image::Image< PixelT > > getImage(lsst::geom::Box2I const &bbox, std::string const &interpStyle, std::string const &undersampleStyle="THROW_EXCEPTION") const
Definition: Background.h:318
UndersampleStyle _asUsedUndersampleStyle
the undersampleStyle we actually used
Definition: Background.h:366
Background & operator=(Background &&)=delete
std::shared_ptr< math::Approximate< InternalPixelT > > getApproximate(ApproximateControl const &actrl, UndersampleStyle const undersampleStyle=THROW_EXCEPTION) const
Method to return an approximation to the background.
Definition: Background.h:348
std::shared_ptr< lsst::afw::image::Image< PixelT > > getImage() const
Method to interpolate and return the background for entire image.
Definition: Background.h:329
std::vector< int > _ysize
y size ...
Definition: Background.h:373
std::shared_ptr< lsst::afw::image::Image< PixelT > > getImage(std::string const &interpStyle, std::string const &undersampleStyle="THROW_EXCEPTION") const
Method to interpolate and return the background for entire image.
Definition: Background.h:296
virtual ~Background()=default
dtor
float InternalPixelT
type used for any internal images, and returned by getApproximate
Definition: Background.h:262
std::vector< int > _yorig
y origin ...
Definition: Background.h:371
Interpolate::Style _asUsedInterpStyle
the style we actually used
Definition: Background.h:365
std::shared_ptr< lsst::afw::image::Image< PixelT > > getImage(Interpolate::Style const interpStyle, UndersampleStyle const undersampleStyle=THROW_EXCEPTION) const
Method to interpolate and return the background for entire image.
Definition: Background.h:283
std::shared_ptr< BackgroundControl > _bctrl
control info set by user.
Definition: Background.h:364
A class to evaluate image background levels.
Definition: Background.h:434
BackgroundMI & operator=(BackgroundMI const &)=delete
lsst::afw::image::MaskedImage< InternalPixelT > getStatsImage() const
Return the image of statistical quantities extracted from the image.
Definition: Background.h:490
BackgroundMI & operator=(BackgroundMI &&)=delete
BackgroundMI(BackgroundMI &&)=delete
~BackgroundMI() override=default
BackgroundMI & operator-=(float const delta) override
Subtract a scalar from the Background (equivalent to subtracting a constant from the original image)
BackgroundMI(BackgroundMI const &)=delete
BackgroundMI & operator+=(float const delta) override
Add a scalar to the Background (equivalent to adding a constant to the original image)
BackgroundMI(ImageT const &img, BackgroundControl const &bgCtrl)
Constructor for BackgroundMI.
Definition: BackgroundMI.cc:80
Pass parameters to a Statistics object.
Definition: Statistics.h:92
An integer coordinate rectangle.
Definition: Box.h:55
Reports invalid arguments.
Definition: Runtime.h:66
Reports attempts to exceed implementation-defined length limits for some classes.
Definition: Runtime.h:76
Property
control what is calculated
Definition: Statistics.h:62
@ MEANCLIP
estimate sample N-sigma clipped mean (N set in StatisticsControl, default=3)
Definition: Statistics.h:71
Property stringToStatisticsProperty(std::string const property)
Conversion function to switch a string to a Property (see Statistics.h)
Definition: Statistics.cc:738
Interpolate::Style stringToInterpStyle(std::string const &style)
Conversion function to switch a string to an Interpolate::Style.
Definition: Interpolate.cc:256
UndersampleStyle stringToUndersampleStyle(std::string const &style)
Conversion function to switch a string to an UndersampleStyle.
Definition: Background.cc:117
std::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:526
BOOST_PP_SEQ_FOR_EACH(INSTANTIATE_COLUMNVIEW_SCALAR, _, BOOST_PP_TUPLE_TO_SEQ(AFW_TABLE_SCALAR_FIELD_TYPE_N, AFW_TABLE_SCALAR_FIELD_TYPE_TUPLE)) BOOST_PP_SEQ_FOR_EACH(INSTANTIATE_COLUMNVIEW_ARRAY
def format(config, name=None, writeSourceLine=True, prefix="", verbose=False)
Definition: history.py:174
A base class for image defects.