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

#include <Background.h>

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

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

BackgroundMI &	operator= (BackgroundMI const &)=delete

BackgroundMI &	operator= (BackgroundMI &&)=delete

	~BackgroundMI () override=default

BackgroundMI &	operator+= (float const delta) override
	Add a scalar to the Background (equivalent to adding a constant to the original image) More...

BackgroundMI &	operator-= (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< InternalPixelT >	getStatsImage () 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< BackgroundControl >	getBackgroundControl ()

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);

Deprecated:: 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 468 of file Background.h.

Member Typedef Documentation

◆ InternalPixelT

typedef float lsst::afw::math::Background::InternalPixelT

inherited

type used for any internal images, and returned by getApproximate

Definition at line 293 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

img	ImageT (or MaskedImage) whose properties we want
bgCtrl	Control 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

Deprecated:: The old and deprecated API specified the interpolation style as part of the BackgroundControl object passed to this ctor. This is still supported, but the work isn't done until the getImage() method is called

Definition at line 81 of file BackgroundMI.cc.

         : Background(img, bgCtrl), _statsImage(image::MaskedImage<InternalPixelT>()) {
     // =============================================================
     // Loop over the cells in the image, computing statistical properties
     // of each cell in turn and using them to set _statsImage
     int const nxSample = bgCtrl.getNxSample();
     int const nySample = bgCtrl.getNySample();
     _statsImage = image::MaskedImage<InternalPixelT>(nxSample, nySample);
 
     image::MaskedImage<InternalPixelT>::Image& im = *_statsImage.getImage();
     image::MaskedImage<InternalPixelT>::Variance& var = *_statsImage.getVariance();
 
     for (int iX = 0; iX < nxSample; ++iX) {
         for (int iY = 0; iY < nySample; ++iY) {
             ImageT subimg = ImageT(img,
                                    lsst::geom::Box2I(lsst::geom::Point2I(_xorig[iX], _yorig[iY]),
                                                      lsst::geom::Extent2I(_xsize[iX], _ysize[iY])),
                                    image::LOCAL);
 
             std::pair<double, double> res = makeStatistics(subimg, bgCtrl.getStatisticsProperty() | ERRORS,
                                                            *bgCtrl.getStatisticsControl())
                                                     .getResult();
             im(iX, iY) = res.first;
             var(iX, iY) = res.second;
         }
     }
 }

◆ 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

imageDimensions	unbinned Image's BBox
statsImage	Internal stats image

Definition at line 108 of file BackgroundMI.cc.

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

lsst::afw::math::Background::Background

Background(ImageT const &img, BackgroundControl const &bgCtrl)

Constructor for Background.

Definition: Background.cc:44

lsst::afw::image::MaskedImage::getHeight

int getHeight() const

Return the number of rows in the image.

Definition: MaskedImage.h:1095

lsst::afw::image::MaskedImage::getWidth

int getWidth() const

Return the number of columns in the image.

Definition: MaskedImage.h:1093

◆ 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

actrl	Approximation style
undersampleStyle	Behaviour if there are too few points

Definition at line 381 of file Background.h.

                                                                              {
         InternalPixelT disambiguate = 0;
         return _getApproximate(actrl, undersampleStyle, disambiguate);
     }

◆ 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 370 of file Background.h.

370 { return _asUsedInterpStyle; }

lsst::afw::math::Background::_asUsedInterpStyle

Interpolate::Style _asUsedInterpStyle

the style we actually used

Definition: Background.h:398

◆ 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 374 of file Background.h.

374 { return _asUsedUndersampleStyle; }

lsst::afw::math::Background::_asUsedUndersampleStyle

UndersampleStyle _asUsedUndersampleStyle

the undersampleStyle we actually used

Definition: Background.h:399

◆ getBackgroundControl() [1/2]

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

inlineinherited

Definition at line 392 of file Background.h.

392 { return _bctrl; }

lsst::afw::math::Background::_bctrl

std::shared_ptr< BackgroundControl > _bctrl

control info set by user.

Definition: Background.h:397

◆ getBackgroundControl() [2/2]

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

inlineinherited

Definition at line 393 of file Background.h.

393 { return _bctrl; }

lsst::afw::math::Background::_bctrl

std::shared_ptr< BackgroundControl > _bctrl

control info set by user.

Definition: Background.h:397

◆ getImage() [1/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

interpStyle	Style of the interpolation
undersampleStyle	Behaviour if there are too few points

Returns: A boost shared-pointer to an image containing the estimated background

Definition at line 312 of file Background.h.

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

◆ getImage() [2/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

interpStyle	Style of the interpolation
undersampleStyle	Behaviour if there are too few points

Returns: A boost shared-pointer to an image containing the estimated background

Definition at line 325 of file Background.h.

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

◆ 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

bbox	Bounding box for sub-image
interpStyle	Style of the interpolation
undersampleStyle	Behaviour if there are too few points

Definition at line 336 of file Background.h.

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

◆ 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

bbox	Bounding box for sub-image
interpStyle	Style of the interpolation
undersampleStyle	Behaviour if there are too few points

Definition at line 347 of file Background.h.

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

◆ getImage() [5/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.

Deprecated:: New code should specify the interpolation style in getImage, not the ctor

Definition at line 362 of file Background.h.

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

◆ getImageBBox()

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

inlineinherited

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

Definition at line 390 of file Background.h.

390 { return _imgBBox; }

lsst::afw::math::Background::_imgBBox

lsst::geom::Box2I _imgBBox

size and origin of input image

Definition: Background.h:396

◆ getPixel() [1/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

style	How to interpolate
x	x-pixel coordinate (column)
y	y-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.

                                                                                                 {
     (void)getImage<InternalPixelT>(interpStyle);  // setup the interpolation
 
     // build an interpobj along the row y and get the x'th value
     int const nxSample = _statsImage.getWidth();
     std::vector<double> bg_x(nxSample);
     for (int iX = 0; iX < nxSample; iX++) {
         bg_x[iX] = _gridColumns[iX][y];
     }
     std::vector<double> xcenTmp, bgTmp;
     cullNan(_xcen, bg_x, xcenTmp, bgTmp);
 
     try {
         std::shared_ptr<Interpolate> intobj = makeInterpolate(xcenTmp, bgTmp, interpStyle);
         return static_cast<double>(intobj->interpolate(x));
     } catch (ex::Exception& e) {
         LSST_EXCEPT_ADD(e, "in getPixel()");
         throw;
     }
 }

◆ getPixel() [2/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.

Deprecated:: New code should specify the interpolation style in getPixel, not the ctor

Definition at line 550 of file Background.h.

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

◆ 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 558 of file Background.h.

558 { 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

delta Value to add

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

Definition at line 170 of file BackgroundMI.cc.

                                                         {
     _statsImage += delta;
     return *this;
 }

◆ 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

delta Value to subtract

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

Definition at line 175 of file BackgroundMI.cc.

                                                         {
     _statsImage -= delta;
     return *this;
 }

◆ operator=() [1/2]

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

delete

◆ operator=() [2/2]

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

delete

Member Data Documentation

◆ _asUsedInterpStyle

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

mutableprotectedinherited

the style we actually used

Definition at line 398 of file Background.h.

◆ _asUsedUndersampleStyle

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

mutableprotectedinherited

the undersampleStyle we actually used

Definition at line 399 of file Background.h.

◆ _bctrl

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

protectedinherited

control info set by user.

Definition at line 397 of file Background.h.

◆ _imgBBox

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

protectedinherited

size and origin of input image

Definition at line 396 of file Background.h.

◆ _xcen

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

protectedinherited

x center pix coords of sub images

Definition at line 401 of file Background.h.

◆ _xorig

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

protectedinherited

x origin pix coords of sub images

Definition at line 403 of file Background.h.

◆ _xsize

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

protectedinherited

x size of sub images

Definition at line 405 of file Background.h.

◆ _ycen

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

protectedinherited

y center ...

Definition at line 402 of file Background.h.

◆ _yorig

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

protectedinherited

y origin ...

Definition at line 404 of file Background.h.

◆ _ysize

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

protectedinherited

y size ...

Definition at line 406 of file Background.h.

The documentation for this class was generated from the following files:

/j/snowflake/release/lsstsw/stack/Linux64/afw/19.0.0-4-ga671dab3b+1/include/lsst/afw/math/Background.h
/j/snowflake/release/lsstsw/stack/Linux64/afw/19.0.0-4-ga671dab3b+1/src/math/BackgroundMI.cc

Public Types

Public Member Functions

Protected Attributes

Detailed Description

Member Typedef Documentation

◆ InternalPixelT

Constructor & Destructor Documentation

◆ BackgroundMI() [1/4]

◆ BackgroundMI() [2/4]

◆ BackgroundMI() [3/4]

◆ BackgroundMI() [4/4]

◆ ~BackgroundMI()

Member Function Documentation

◆ getApproximate()

◆ getAsUsedInterpStyle()

◆ getAsUsedUndersampleStyle()

◆ getBackgroundControl() [1/2]

◆ getBackgroundControl() [2/2]

◆ getImage() [1/5]

◆ getImage() [2/5]

◆ getImage() [3/5]

◆ getImage() [4/5]

◆ getImage() [5/5]

◆ getImageBBox()

◆ getPixel() [1/2]

◆ getPixel() [2/2]

◆ getStatsImage()

◆ operator+=()

◆ operator-=()

◆ operator=() [1/2]

◆ operator=() [2/2]

Member Data Documentation

◆ _asUsedInterpStyle

◆ _asUsedUndersampleStyle

◆ _bctrl

◆ _imgBBox

◆ _xcen

◆ _xorig

◆ _xsize

◆ _ycen

◆ _yorig

◆ _ysize