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

#include <Background.h>

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

Public Types
using	InternalPixelT = float
	type used for any internal images, and returned by getApproximate

Public Member Functions
template<typename ImageT>
	BackgroundMI (ImageT const &img, BackgroundControl const &bgCtrl)
	Constructor for BackgroundMI.

	BackgroundMI (lsst::geom::Box2I const imageDimensions, image::MaskedImage< InternalPixelT > const &statsImage)
	Recreate a BackgroundMI from the statsImage and the original Image's BBox.

	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)

BackgroundMI &	operator-= (float const delta) override
	Subtract a scalar from the Background (equivalent to subtracting a constant from the original image)

lsst::afw::image::MaskedImage< InternalPixelT >	getStatsImage () const
	Return the image of statistical quantities extracted from the image.

ndarray::Array< double, 1, 1 >	getBinCentersX () const
	Return the x-coordinate centers of the bins.

ndarray::Array< double, 1, 1 >	getBinCentersY () const
	Return the y-coordinate centers of the bins.

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.

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.

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.

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

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

std::shared_ptr< math::Approximate< InternalPixelT > >	getApproximate (ApproximateControl const &actrl, UndersampleStyle const undersampleStyle=THROW_EXCEPTION) const
	Method to return an approximation to the background.

lsst::geom::Box2I	getImageBBox () const
	Return the input image's (PARENT) bounding box.

std::shared_ptr< BackgroundControl >	getBackgroundControl ()

std::shared_ptr< BackgroundControl const >	getBackgroundControl () const

Protected Attributes
lsst::geom::Box2I	_imgBBox
	size and origin of input image

std::shared_ptr< BackgroundControl >	_bctrl
	control info set by user.

Interpolate::Style	_asUsedInterpStyle
	the style we actually used

UndersampleStyle	_asUsedUndersampleStyle
	the undersampleStyle we actually used

std::vector< double >	_xcen
	x center pix coords of sub images

std::vector< double >	_ycen
	y center ...

std::vector< int >	_xorig
	x origin pix coords of sub images

std::vector< int >	_yorig
	y origin ...

std::vector< int >	_xsize
	x size of sub images

std::vector< int >	_ysize
	y size ...

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

Member Typedef Documentation

◆ InternalPixelT

using lsst::afw::math::Background::InternalPixelT = float

inherited

type used for any internal images, and returned by getApproximate

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

Definition at line 80 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 107 of file BackgroundMI.cc.

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

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

int getHeight() const

Return the number of rows in the image.

Definition MaskedImage.h:1057

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

int getWidth() const

Return the number of columns in the image.

Definition MaskedImage.h:1055

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

338{ return _asUsedInterpStyle; }

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

Interpolate::Style _asUsedInterpStyle

the style we actually used

Definition Background.h:366

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

342{ return _asUsedUndersampleStyle; }

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

UndersampleStyle _asUsedUndersampleStyle

the undersampleStyle we actually used

Definition Background.h:367

◆ getBackgroundControl() [1/2]

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

inlineinherited

Definition at line 360 of file Background.h.

360{ return _bctrl; }

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

std::shared_ptr< BackgroundControl > _bctrl

control info set by user.

Definition Background.h:365

◆ getBackgroundControl() [2/2]

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

inlineinherited

Definition at line 361 of file Background.h.

361{ return _bctrl; }

◆ getBinCentersX()

ndarray::Array< double, 1, 1 > lsst::afw::math::BackgroundMI::getBinCentersX ( ) const

Return the x-coordinate centers of the bins.

Definition at line 179 of file BackgroundMI.cc.

                                                              {
    ndarray::Array<double, 1, 1> result = ndarray::allocate(_xcen.size());
    std::copy(_xcen.begin(), _xcen.end(), result.begin());
    result.deep() += _imgBBox.getMinX();
    return result;
}

◆ getBinCentersY()

ndarray::Array< double, 1, 1 > lsst::afw::math::BackgroundMI::getBinCentersY ( ) const

Return the y-coordinate centers of the bins.

Definition at line 186 of file BackgroundMI.cc.

                                                              {
    ndarray::Array<double, 1, 1> result = ndarray::allocate(_ycen.size());
    std::copy(_ycen.begin(), _ycen.end(), result.begin());
    result.deep() += _imgBBox.getMinY();
    return result;
}

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

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

◆ 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

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

                                                                             {
        return getImage<PixelT>(_imgBBox, interpStyle, 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 308 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 319 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	(	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 297 of file Background.h.

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

◆ getImageBBox()

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

inlineinherited

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

Definition at line 358 of file Background.h.

358{ return _imgBBox; }

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

491{ 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 169 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 174 of file BackgroundMI.cc.

                                                        {
    _statsImage -= delta;
    return *this;
}

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

◆ _asUsedUndersampleStyle

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

mutableprotectedinherited

the undersampleStyle we actually used

Definition at line 367 of file Background.h.

◆ _bctrl

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

protectedinherited

control info set by user.

Definition at line 365 of file Background.h.

◆ _imgBBox

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

protectedinherited

size and origin of input image

Definition at line 364 of file Background.h.

◆ _xcen

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

protectedinherited

x center pix coords of sub images

Definition at line 369 of file Background.h.

◆ _xorig

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

protectedinherited

x origin pix coords of sub images

Definition at line 371 of file Background.h.

◆ _xsize

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

protectedinherited

x size of sub images

Definition at line 373 of file Background.h.

◆ _ycen

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

protectedinherited

y center ...

Definition at line 370 of file Background.h.

◆ _yorig

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

protectedinherited

y origin ...

Definition at line 372 of file Background.h.

◆ _ysize

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

protectedinherited

y size ...

Definition at line 374 of file Background.h.

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

/j/snowflake/release/lsstsw/stack/lsst-scipipe-12.1.0/Linux/afw/g7ae74a0b1c+a25e60b391/include/lsst/afw/math/Background.h
/j/snowflake/release/lsstsw/stack/lsst-scipipe-12.1.0/Linux/afw/g7ae74a0b1c+a25e60b391/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]

◆ getBinCentersX()

◆ getBinCentersY()

◆ getImage() [1/5]

◆ getImage() [2/5]

◆ getImage() [3/5]

◆ getImage() [4/5]

◆ getImage() [5/5]

◆ getImageBBox()

◆ getStatsImage()

◆ operator+=()

◆ operator-=()

◆ operator=() [1/2]

◆ operator=() [2/2]

Member Data Documentation

◆ _asUsedInterpStyle

◆ _asUsedUndersampleStyle

◆ _bctrl

◆ _imgBBox

◆ _xcen

◆ _xorig

◆ _xsize

◆ _ycen

◆ _yorig

◆ _ysize