LSSTApplications  19.0.0-14-gb0260a2+b89439f59d,20.0.0+126303c00d,20.0.0+2f3d0e5c40,20.0.0+36ef800059,20.0.0+6ab788e194,20.0.0+a788ff1d83,20.0.0+b545961afb,20.0.0+bebc1f60e8,20.0.0+e2e26847c2,20.0.0+ec00f03e9c,20.0.0-1-g10df615+b92a01c08d,20.0.0-1-g253301a+36ef800059,20.0.0-1-g2b7511a+bebc1f60e8,20.0.0-1-g4d801e7+7c74587066,20.0.0-1-g5b95a8c+3e2d406de1,20.0.0-1-g660595b+f45b7d88f4,20.0.0-1-gc96f8cb+665e8551f1,20.0.0-1-gd1c87d7+85c46248f3,20.0.0-1-gedffbd8+ca2c461684,20.0.0-14-g1ce627f+450400e286,20.0.0-16-g111fe95+665e8551f1,20.0.0-16-g233ea98+b7ef15a6f8,20.0.0-17-ga9337b4+235318a901,20.0.0-2-g4dae9ad+665e8551f1,20.0.0-2-g7818986+85c46248f3,20.0.0-2-gec03fae+ff10c6d78d,20.0.0-25-g38d2b7ae+6870ac0cf6,20.0.0-3-g4cc78c6+63636aeed8,20.0.0-3-g6a8623c+450400e286,20.0.0-3-g750bffe+50c7740d2d,20.0.0-4-gfea843c+f45b7d88f4,20.0.0-48-gd64a390+cf2ddfd0ca,20.0.0-5-g357b56b+f45b7d88f4,20.0.0-5-gfcebe35+806271b712,20.0.0-7-gc818c6e6+7d435f9f99,20.0.0-7-gcda7bf1+1884c7ddc6,20.0.0-9-g61a2a9a3d+14f89e4eca,w.2020.39
LSSTDataManagementBasePackage
Public Types | Public Member Functions | Protected Attributes | List of all members
lsst::afw::math::BackgroundMI Class Reference

A class to evaluate image background levels. More...

#include <Background.h>

Inheritance diagram for lsst::afw::math::BackgroundMI:
lsst::afw::math::Background

Public Types

typedef float InternalPixelT
 type used for any internal images, and returned by getApproximate More...
 

Public Member Functions

template<typename ImageT >
 BackgroundMI (ImageT const &img, BackgroundControl const &bgCtrl)
 Constructor for BackgroundMI. More...
 
 BackgroundMI (lsst::geom::Box2I const imageDimensions, image::MaskedImage< InternalPixelT > const &statsImage)
 Recreate a BackgroundMI from the statsImage and the original Image's BBox. More...
 
 BackgroundMI (BackgroundMI const &)=delete
 
 BackgroundMI (BackgroundMI &&)=delete
 
BackgroundMIoperator= (BackgroundMI const &)=delete
 
BackgroundMIoperator= (BackgroundMI &&)=delete
 
 ~BackgroundMI () override=default
 
BackgroundMIoperator+= (float const delta) override
 Add a scalar to the Background (equivalent to adding a constant to the original image) More...
 
BackgroundMIoperator-= (float const delta) override
 Subtract a scalar from the Background (equivalent to subtracting a constant from the original image) More...
 
double getPixel (Interpolate::Style const style, int const x, int const y) const
 Method to retrieve the background level at a pixel coord. More...
 
double getPixel (int const x, int const y) const
 Return the background value at a point. More...
 
lsst::afw::image::MaskedImage< InternalPixelTgetStatsImage () const
 Return the image of statistical quantities extracted from the image. More...
 
template<typename PixelT >
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. More...
 
template<typename PixelT >
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. More...
 
template<typename PixelT >
std::shared_ptr< lsst::afw::image::Image< PixelT > > getImage (lsst::geom::Box2I const &bbox, Interpolate::Style const interpStyle, UndersampleStyle const undersampleStyle=THROW_EXCEPTION) const
 
template<typename PixelT >
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
 
template<typename PixelT >
std::shared_ptr< lsst::afw::image::Image< PixelT > > getImage () const
 Method to interpolate and return the background for entire image. More...
 
Interpolate::Style getAsUsedInterpStyle () const
 Return the Interpolate::Style that we actually used in the last call to getImage() More...
 
UndersampleStyle getAsUsedUndersampleStyle () const
 Return the UndersampleStyle that we actually used in the last call to getImage() More...
 
std::shared_ptr< math::Approximate< InternalPixelT > > getApproximate (ApproximateControl const &actrl, UndersampleStyle const undersampleStyle=THROW_EXCEPTION) const
 Method to return an approximation to the background. More...
 
lsst::geom::Box2I getImageBBox () const
 Return the input image's (PARENT) bounding box. More...
 
std::shared_ptr< BackgroundControlgetBackgroundControl ()
 
std::shared_ptr< BackgroundControl const > getBackgroundControl () const
 

Protected Attributes

lsst::geom::Box2I _imgBBox
 size and origin of input image More...
 
std::shared_ptr< BackgroundControl_bctrl
 control info set by user. More...
 
Interpolate::Style _asUsedInterpStyle
 the style we actually used More...
 
UndersampleStyle _asUsedUndersampleStyle
 the undersampleStyle we actually used More...
 
std::vector< double > _xcen
 x center pix coords of sub images More...
 
std::vector< double > _ycen
 y center ... More...
 
std::vector< int > _xorig
 x origin pix coords of sub images More...
 
std::vector< int > _yorig
 y origin ... More...
 
std::vector< int > _xsize
 x size of sub images More...
 
std::vector< int > _ysize
 y size ... More...
 

Detailed Description

A class to evaluate image background levels.

Break an image up into nx*ny sub-images and use a statistical to estimate the background levels in each square. Then use a user-specified or algorithm to estimate background at a given pixel coordinate.

Methods are available to return the background at a point (inefficiently), or an entire background image. BackgroundControl contains a public StatisticsControl member to allow user control of how the backgrounds are computed.

math::BackgroundControl bctrl(7, 7);  // number of sub-image squares in {x,y}-dimensions
bctrl.sctrl.setNumSigmaClip(5.0);     // use 5-sigma clipping for the sub-image means
std::shared_ptr<math::Background> backobj = math::makeBackground(img, bctrl);
// get a whole background image
Image<PixelT> back = backobj->getImage<PixelT>(math::Interpolate::NATURAL_SPLINE);

there is also

// get the background at a pixel at i_x,i_y
double someValue = backobj.getPixel(math::Interpolate::LINEAR, i_x, i_y);

Definition at line 434 of file Background.h.

Member Typedef Documentation

◆ InternalPixelT

type used for any internal images, and returned by getApproximate

Definition at line 264 of file Background.h.

Constructor & Destructor Documentation

◆ BackgroundMI() [1/4]

template<typename ImageT >
lsst::afw::math::BackgroundMI::BackgroundMI ( ImageT const &  img,
BackgroundControl const &  bgCtrl 
)
explicit

Constructor for BackgroundMI.

Estimate the statistical properties of the Image in a grid of cells; we'll later call getImage() to interpolate those values, creating an image the same size as the original

Parameters
imgImageT (or MaskedImage) whose properties we want
bgCtrlControl how the BackgroundMI is estimated
Note
If there are heavily masked or Nan regions in the image we may not be able to estimate all the cells in the "statsImage". Interpolation will still work, but if you want to prevent the code wildly extrapolating, it may be better to set the values directly; e.g.
defaultValue = 10
statsImage = afwMath.cast_BackgroundMI(bkgd).getStatsImage()
sim = statsImage.getImage().getArray()
sim[np.isnan(sim)] = defaultValue # replace NaN by defaultValue
bkgdImage = bkgd.getImageF(afwMath.Interpolate.NATURAL_SPLINE, afwMath.REDUCE_INTERP_ORDER)

There is a ticket (#2825) to allow getImage to specify a default value to use when interpolation fails

Definition at line 81 of file BackgroundMI.cc.

82  : Background(img, bgCtrl), _statsImage(image::MaskedImage<InternalPixelT>()) {
83  // =============================================================
84  // Loop over the cells in the image, computing statistical properties
85  // of each cell in turn and using them to set _statsImage
86  int const nxSample = bgCtrl.getNxSample();
87  int const nySample = bgCtrl.getNySample();
88  _statsImage = image::MaskedImage<InternalPixelT>(nxSample, nySample);
89 
92 
93  for (int iX = 0; iX < nxSample; ++iX) {
94  for (int iY = 0; iY < nySample; ++iY) {
95  ImageT subimg = ImageT(img,
98  image::LOCAL);
99 
100  std::pair<double, double> res = makeStatistics(subimg, bgCtrl.getStatisticsProperty() | ERRORS,
101  *bgCtrl.getStatisticsControl())
102  .getResult();
103  im(iX, iY) = res.first;
104  var(iX, iY) = res.second;
105  }
106  }
107 }

◆ BackgroundMI() [2/4]

lsst::afw::math::BackgroundMI::BackgroundMI ( lsst::geom::Box2I const  imageDimensions,
image::MaskedImage< InternalPixelT > const &  statsImage 
)
explicit

Recreate a BackgroundMI from the statsImage and the original Image's BBox.

Parameters
imageDimensionsunbinned Image's BBox
statsImageInternal stats image

Definition at line 108 of file BackgroundMI.cc.

110  : Background(imageBBox, statsImage.getWidth(), statsImage.getHeight()), _statsImage(statsImage) {}

◆ BackgroundMI() [3/4]

lsst::afw::math::BackgroundMI::BackgroundMI ( BackgroundMI const &  )
delete

◆ BackgroundMI() [4/4]

lsst::afw::math::BackgroundMI::BackgroundMI ( BackgroundMI &&  )
delete

◆ ~BackgroundMI()

lsst::afw::math::BackgroundMI::~BackgroundMI ( )
overridedefault

Member Function Documentation

◆ getApproximate()

std::shared_ptr<math::Approximate<InternalPixelT> > lsst::afw::math::Background::getApproximate ( ApproximateControl const &  actrl,
UndersampleStyle const  undersampleStyle = THROW_EXCEPTION 
) const
inlineinherited

Method to return an approximation to the background.

Parameters
actrlApproximation style
undersampleStyleBehaviour if there are too few points

Definition at line 348 of file Background.h.

350  {
351  InternalPixelT disambiguate = 0;
352  return _getApproximate(actrl, undersampleStyle, disambiguate);
353  }

◆ getAsUsedInterpStyle()

Interpolate::Style lsst::afw::math::Background::getAsUsedInterpStyle ( ) const
inlineinherited

Return the Interpolate::Style that we actually used in the last call to getImage()

N.b. Interpolate can fallback to a lower order if there aren't enough samples

Definition at line 337 of file Background.h.

337 { return _asUsedInterpStyle; }

◆ getAsUsedUndersampleStyle()

UndersampleStyle lsst::afw::math::Background::getAsUsedUndersampleStyle ( ) const
inlineinherited

Return the UndersampleStyle that we actually used in the last call to getImage()

Definition at line 341 of file Background.h.

341 { return _asUsedUndersampleStyle; }

◆ getBackgroundControl() [1/2]

std::shared_ptr<BackgroundControl> lsst::afw::math::Background::getBackgroundControl ( )
inlineinherited

Definition at line 359 of file Background.h.

359 { return _bctrl; }

◆ getBackgroundControl() [2/2]

std::shared_ptr<BackgroundControl const> lsst::afw::math::Background::getBackgroundControl ( ) const
inlineinherited

Definition at line 360 of file Background.h.

360 { return _bctrl; }

◆ getImage() [1/5]

template<typename PixelT >
std::shared_ptr<lsst::afw::image::Image<PixelT> > lsst::afw::math::Background::getImage ( ) const
inlineinherited

Method to interpolate and return the background for entire image.

Definition at line 329 of file Background.h.

329  {
330  return getImage<PixelT>(_bctrl->getInterpStyle(), _bctrl->getUndersampleStyle());
331  }

◆ getImage() [2/5]

template<typename PixelT >
std::shared_ptr<lsst::afw::image::Image<PixelT> > lsst::afw::math::Background::getImage ( Interpolate::Style const  interpStyle,
UndersampleStyle const  undersampleStyle = THROW_EXCEPTION 
) const
inlineinherited

Method to interpolate and return the background for entire image.

Parameters
interpStyleStyle of the interpolation
undersampleStyleBehaviour if there are too few points
Returns
A boost shared-pointer to an image containing the estimated background

Definition at line 283 of file Background.h.

285  {
286  return getImage<PixelT>(_imgBBox, interpStyle, undersampleStyle);
287  }

◆ getImage() [3/5]

template<typename PixelT >
std::shared_ptr<lsst::afw::image::Image<PixelT> > lsst::afw::math::Background::getImage ( lsst::geom::Box2I const &  bbox,
Interpolate::Style const  interpStyle,
UndersampleStyle const  undersampleStyle = THROW_EXCEPTION 
) const
inlineinherited
Parameters
bboxBounding box for sub-image
interpStyleStyle of the interpolation
undersampleStyleBehaviour if there are too few points

Definition at line 307 of file Background.h.

309  {
310  return _getImage(bbox, interpStyle, undersampleStyle, static_cast<PixelT>(0));
311  }

◆ getImage() [4/5]

template<typename PixelT >
std::shared_ptr<lsst::afw::image::Image<PixelT> > lsst::afw::math::Background::getImage ( lsst::geom::Box2I const &  bbox,
std::string const &  interpStyle,
std::string const &  undersampleStyle = "THROW_EXCEPTION" 
) const
inlineinherited
Parameters
bboxBounding box for sub-image
interpStyleStyle of the interpolation
undersampleStyleBehaviour if there are too few points

Definition at line 318 of file Background.h.

320  {
321  return _getImage(bbox, math::stringToInterpStyle(interpStyle),
322  stringToUndersampleStyle(undersampleStyle), static_cast<PixelT>(0));
323  }

◆ getImage() [5/5]

template<typename PixelT >
std::shared_ptr<lsst::afw::image::Image<PixelT> > lsst::afw::math::Background::getImage ( std::string const &  interpStyle,
std::string const &  undersampleStyle = "THROW_EXCEPTION" 
) const
inlineinherited

Method to interpolate and return the background for entire image.

Parameters
interpStyleStyle of the interpolation
undersampleStyleBehaviour if there are too few points
Returns
A boost shared-pointer to an image containing the estimated background

Definition at line 296 of file Background.h.

297  {
298  return getImage<PixelT>(math::stringToInterpStyle(interpStyle),
299  stringToUndersampleStyle(undersampleStyle));
300  }

◆ getImageBBox()

lsst::geom::Box2I lsst::afw::math::Background::getImageBBox ( ) const
inlineinherited

Return the input image's (PARENT) bounding box.

Definition at line 357 of file Background.h.

357 { return _imgBBox; }

◆ getPixel() [1/2]

double lsst::afw::math::BackgroundMI::getPixel ( int const  x,
int const  y 
) const
inline

Return the background value at a point.

Warning
This is very inefficient – only use it for debugging, if then.

Definition at line 509 of file Background.h.

509  {
510  // I think this should be LOCAL because the original getPixel used 0-based indices
511  return getImage<float>()->get(lsst::geom::Point2I(x, y), image::LOCAL);
512  }

◆ getPixel() [2/2]

double lsst::afw::math::BackgroundMI::getPixel ( Interpolate::Style const  style,
int const  x,
int const  y 
) const

Method to retrieve the background level at a pixel coord.

Parameters
styleHow to interpolate
xx-pixel coordinate (column)
yy-pixel coordinate (row)
Returns
an estimated background at x,y (double)
Deprecated:
Don't call this image (not even in test code). This can be a very costly function to get a single pixel. If you want an image, use the getImage() method.

Definition at line 180 of file BackgroundMI.cc.

180  {
181  (void)getImage<InternalPixelT>(interpStyle); // setup the interpolation
182 
183  // build an interpobj along the row y and get the x'th value
184  int const nxSample = _statsImage.getWidth();
185  std::vector<double> bg_x(nxSample);
186  for (int iX = 0; iX < nxSample; iX++) {
187  bg_x[iX] = _gridColumns[iX][y];
188  }
189  std::vector<double> xcenTmp, bgTmp;
190  cullNan(_xcen, bg_x, xcenTmp, bgTmp);
191 
192  try {
193  std::shared_ptr<Interpolate> intobj = makeInterpolate(xcenTmp, bgTmp, interpStyle);
194  return static_cast<double>(intobj->interpolate(x));
195  } catch (ex::Exception& e) {
196  LSST_EXCEPT_ADD(e, "in getPixel()");
197  throw;
198  }
199 }

◆ getStatsImage()

lsst::afw::image::MaskedImage<InternalPixelT> lsst::afw::math::BackgroundMI::getStatsImage ( ) const
inline

Return the image of statistical quantities extracted from the image.

Definition at line 516 of file Background.h.

516 { return _statsImage; }

◆ operator+=()

BackgroundMI & lsst::afw::math::BackgroundMI::operator+= ( float const  delta)
overridevirtual

Add a scalar to the Background (equivalent to adding a constant to the original image)

Parameters
deltaValue to add

Implements lsst::afw::math::Background.

Definition at line 170 of file BackgroundMI.cc.

170  {
171  _statsImage += delta;
172  return *this;
173 }

◆ operator-=()

BackgroundMI & lsst::afw::math::BackgroundMI::operator-= ( float const  delta)
overridevirtual

Subtract a scalar from the Background (equivalent to subtracting a constant from the original image)

Parameters
deltaValue to subtract

Implements lsst::afw::math::Background.

Definition at line 175 of file BackgroundMI.cc.

175  {
176  _statsImage -= delta;
177  return *this;
178 }

◆ operator=() [1/2]

BackgroundMI& lsst::afw::math::BackgroundMI::operator= ( BackgroundMI &&  )
delete

◆ operator=() [2/2]

BackgroundMI& lsst::afw::math::BackgroundMI::operator= ( BackgroundMI const &  )
delete

Member Data Documentation

◆ _asUsedInterpStyle

Interpolate::Style lsst::afw::math::Background::_asUsedInterpStyle
mutableprotectedinherited

the style we actually used

Definition at line 365 of file Background.h.

◆ _asUsedUndersampleStyle

UndersampleStyle lsst::afw::math::Background::_asUsedUndersampleStyle
mutableprotectedinherited

the undersampleStyle we actually used

Definition at line 366 of file Background.h.

◆ _bctrl

std::shared_ptr<BackgroundControl> lsst::afw::math::Background::_bctrl
protectedinherited

control info set by user.

Definition at line 364 of file Background.h.

◆ _imgBBox

lsst::geom::Box2I lsst::afw::math::Background::_imgBBox
protectedinherited

size and origin of input image

Definition at line 363 of file Background.h.

◆ _xcen

std::vector<double> lsst::afw::math::Background::_xcen
protectedinherited

x center pix coords of sub images

Definition at line 368 of file Background.h.

◆ _xorig

std::vector<int> lsst::afw::math::Background::_xorig
protectedinherited

x origin pix coords of sub images

Definition at line 370 of file Background.h.

◆ _xsize

std::vector<int> lsst::afw::math::Background::_xsize
protectedinherited

x size of sub images

Definition at line 372 of file Background.h.

◆ _ycen

std::vector<double> lsst::afw::math::Background::_ycen
protectedinherited

y center ...

Definition at line 369 of file Background.h.

◆ _yorig

std::vector<int> lsst::afw::math::Background::_yorig
protectedinherited

y origin ...

Definition at line 371 of file Background.h.

◆ _ysize

std::vector<int> lsst::afw::math::Background::_ysize
protectedinherited

y size ...

Definition at line 373 of file Background.h.


The documentation for this class was generated from the following files:
y
int y
Definition: SpanSet.cc:49
lsst::afw::math::stringToInterpStyle
Interpolate::Style stringToInterpStyle(std::string const &style)
Conversion function to switch a string to an Interpolate::Style.
Definition: Interpolate.cc:257
lsst::afw::math::makeInterpolate
std::shared_ptr< Interpolate > makeInterpolate(std::vector< double > const &x, std::vector< double > const &y, Interpolate::Style const style=Interpolate::AKIMA_SPLINE)
A factory function to make Interpolate objects.
Definition: Interpolate.cc:343
lsst::afw::image::LOCAL
@ LOCAL
Definition: ImageBase.h:94
std::shared_ptr
STL class.
lsst::afw::math::Background::_ysize
std::vector< int > _ysize
y size ...
Definition: Background.h:373
std::pair< double, double >
std::vector< double >
LSST_EXCEPT_ADD
#define LSST_EXCEPT_ADD(e, m)
Add the current location and a message to an existing exception before rethrowing it.
Definition: Exception.h:54
lsst::ip::diffim::detail::PixelT
float PixelT
Definition: AssessSpatialKernelVisitor.cc:208
lsst::afw::math::Background::Background
Background(ImageT const &img, BackgroundControl const &bgCtrl)
Constructor for Background.
Definition: Background.cc:44
lsst::afw::math::Background::InternalPixelT
float InternalPixelT
type used for any internal images, and returned by getApproximate
Definition: Background.h:264
lsst::afw::image::MaskedImage::getWidth
int getWidth() const
Return the number of columns in the image.
Definition: MaskedImage.h:1093
lsst::afw::image::MaskedImage::getHeight
int getHeight() const
Return the number of rows in the image.
Definition: MaskedImage.h:1095
lsst::afw::math::Background::_yorig
std::vector< int > _yorig
y origin ...
Definition: Background.h:371
lsst::afw::math::makeStatistics
Statistics makeStatistics(lsst::afw::image::Image< Pixel > const &img, lsst::afw::image::Mask< image::MaskPixel > const &msk, int const flags, StatisticsControl const &sctrl=StatisticsControl())
Handle a watered-down front-end to the constructor (no variance)
Definition: Statistics.h:354
lsst::afw::math::Statistics::getResult
Value getResult(Property const prop=NOTHING) const
Return the value and error in the specified statistic (e.g.
Definition: Statistics.cc:931
lsst::afw::image::MaskedImage< InternalPixelT >
lsst::afw::math::Background::_xcen
std::vector< double > _xcen
x center pix coords of sub images
Definition: Background.h:368
lsst::afw::math::Background::_bctrl
std::shared_ptr< BackgroundControl > _bctrl
control info set by user.
Definition: Background.h:364
x
double x
Definition: ChebyshevBoundedField.cc:277
lsst::afw::math::Background::_asUsedUndersampleStyle
UndersampleStyle _asUsedUndersampleStyle
the undersampleStyle we actually used
Definition: Background.h:366
lsst::afw::math::Background::_xsize
std::vector< int > _xsize
x size of sub images
Definition: Background.h:372
lsst::afw::math::ERRORS
@ ERRORS
Include errors of requested quantities.
Definition: Statistics.h:65
lsst::afw::image::MaskedImage::getVariance
VariancePtr getVariance() const
Return a (shared_ptr to) the MaskedImage's variance.
Definition: MaskedImage.h:1090
lsst::afw::math::Background::_xorig
std::vector< int > _xorig
x origin pix coords of sub images
Definition: Background.h:370
lsst::afw::math::Background::_asUsedInterpStyle
Interpolate::Style _asUsedInterpStyle
the style we actually used
Definition: Background.h:365
lsst::geom::Point< int, 2 >
lsst::geom::Box2I
An integer coordinate rectangle.
Definition: Box.h:55
lsst::afw::math::Background::_imgBBox
lsst::geom::Box2I _imgBBox
size and origin of input image
Definition: Background.h:363
lsst::afw::image::MaskedImage::getImage
ImagePtr getImage() const
Return a (shared_ptr to) the MaskedImage's image.
Definition: MaskedImage.h:1057
lsst.pex::exceptions::Exception
Provides consistent interface for LSST exceptions.
Definition: Exception.h:107
lsst::afw::math::stringToUndersampleStyle
UndersampleStyle stringToUndersampleStyle(std::string const &style)
Conversion function to switch a string to an UndersampleStyle.
Definition: Background.cc:117
lsst::geom::Extent< int, 2 >
bbox
AmpInfoBoxKey bbox
Definition: Amplifier.cc:117