lsst::afw::math::BackgroundMI Class Reference

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

#include <Background.h>

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

Public Member Functions
template<typename ImageT >
	BackgroundMI (ImageT const &img, BackgroundControl const &bgCtrl)
	Constructor for BackgroundMI. More...
	BackgroundMI (geom::Box2I const imageDimensions, image::MaskedImage< InternalPixelT > const &statsImage)
virtual void	operator+= (float const delta)
	Add a scalar to the Background (equivalent to adding a constant to the original image) More...
virtual void	operator-= (float const delta)
	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...
Public Member Functions inherited from lsst::afw::math::Background
template<typename PixelT >
boost::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 >
boost::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 >
boost::shared_ptr < lsst::afw::image::Image < PixelT > >	getImage (lsst::afw::geom::Box2I const &bbox, Interpolate::Style const interpStyle, UndersampleStyle const undersampleStyle=THROW_EXCEPTION) const
template<typename PixelT >
boost::shared_ptr < lsst::afw::image::Image < PixelT > >	getImage (lsst::afw::geom::Box2I const &bbox, std::string const &interpStyle, std::string const &undersampleStyle="THROW_EXCEPTION") const
template<typename PixelT >
boost::shared_ptr < lsst::afw::image::Image < PixelT > >	getImage () const
	Method to interpolate and return the background for entire image. More...
Interpolate::Style	getAsUsedInterpStyle () const
UndersampleStyle	getAsUsedUndersampleStyle () const
boost::shared_ptr < math::Approximate < InternalPixelT > >	getApproximate (ApproximateControl const &actrl, UndersampleStyle const undersampleStyle=THROW_EXCEPTION) const
	Method to return an approximation to the background. More...
geom::Box2I	getImageBBox () const
boost::shared_ptr < BackgroundControl >	getBackgroundControl ()
boost::shared_ptr < BackgroundControl const >	getBackgroundControl () const
Public Member Functions inherited from lsst::daf::base::Citizen
	Citizen (const std::type_info &)
	Citizen (Citizen const &)
	~Citizen ()
Citizen &	operator= (Citizen const &)
std::string	repr () const
	Return a string representation of a Citizen. More...
void	markPersistent (void)
	Mark a Citizen as persistent and not destroyed until process end. More...
memId	getId () const
	Return the Citizen's ID. More...

Private Member Functions
void	_setGridColumns (Interpolate::Style const interpStyle, UndersampleStyle const undersampleStyle, int const iX, std::vector< int > const &ypix) const
template<typename PixelT >
boost::shared_ptr < image::Image< PixelT > >	doGetImage (geom::Box2I const &bbox, Interpolate::Style const interpStyle_, UndersampleStyle const undersampleStyle) const
template<typename PixelT >
boost::shared_ptr< Approximate < PixelT > >	doGetApproximate (ApproximateControl const &actrl, UndersampleStyle const undersampleStyle) const

Private Attributes
lsst::afw::image::MaskedImage < InternalPixelT >	_statsImage
std::vector< std::vector < double > >	_gridColumns

Additional Inherited Members
Public Types inherited from lsst::afw::math::Background
typedef float	InternalPixelT
	type used for any internal images, and returned by getApproximate More...
Public Types inherited from lsst::daf::base::Citizen
enum	{ magicSentinel = 0xdeadbeef }
typedef unsigned long	memId
	Type of the block's ID. More...
typedef memId(*	memNewCallback )(const memId cid)
	A function used to register a callback. More...
typedef memId(*	memCallback )(const Citizen *ptr)
Static Public Member Functions inherited from lsst::daf::base::Citizen
static bool	hasBeenCorrupted ()
	Check all allocated blocks for corruption. More...
static memId	getNextMemId ()
	Return the memId of the next object to be allocated. More...
static int	init ()
	Called once when the memory system is being initialised. More...
static int	census (int, memId startingMemId=0)
	How many active Citizens are there? More...
static void	census (std::ostream &stream, memId startingMemId=0)
	Print a list of all active Citizens to stream, sorted by ID. More...
static const std::vector < const Citizen * > *	census ()
	Return a (newly allocated) std::vector of active Citizens sorted by ID. More...
static memId	setNewCallbackId (memId id)
	Call the NewCallback when block is allocated. More...
static memId	setDeleteCallbackId (memId id)
	Call the current DeleteCallback when block is deleted. More...
static memNewCallback	setNewCallback (memNewCallback func)
	Set the NewCallback function. More...
static memCallback	setDeleteCallback (memCallback func)
	Set the DeleteCallback function. More...
static memCallback	setCorruptionCallback (memCallback func)
	Set the CorruptionCallback function. More...
Protected Member Functions inherited from lsst::afw::math::Background
template<typename ImageT >
	Background (ImageT const &img, BackgroundControl const &bgCtrl)
	Constructor for Background. More...
	Background (geom::Box2I const imageBBox, int const nx, int const ny)
virtual	~Background ()
	dtor More...
Protected Attributes inherited from lsst::afw::math::Background
geom::Box2I	_imgBBox
	size and origin of input image More...
boost::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
      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 403 of file Background.h.

Constructor & Destructor Documentation

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

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

Parameters

img	ImageT (or MaskedImage) whose properties we want
bgCtrl	Control how the BackgroundMI is estimated

Definition at line 109 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, geom::Box2I(geom::Point2I(_xorig[iX], _yorig[iY]),
                                                    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;
        }
    }
}

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

explicit

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

Parameters

imageBBox	unbinned Image's BBox
statsImage	Internal stats image

Definition at line 139 of file BackgroundMI.cc.

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

Member Function Documentation

void lsst::afw::math::BackgroundMI::_setGridColumns ( Interpolate::Style const  interpStyle, UndersampleStyle const  undersampleStyle, int const  iX, std::vector< int > const &  ypix  ) const

private

Definition at line 147 of file BackgroundMI.cc.

{
    image::MaskedImage<InternalPixelT>::Image &im = *_statsImage.getImage();

    int const height = _imgBBox.getHeight();
    _gridColumns[iX].resize(height);

    // Set _grid as a transitional measure
    std::vector<double> _grid(_statsImage.getHeight());
    std::copy(im.col_begin(iX), im.col_end(iX), _grid.begin());
    
    // remove nan from the grid values before computing columns
    // if we do it here (ie. in _setGridColumns), it should
    // take care of all future occurrences, so we don't need to do this elsewhere
    std::vector<double> ycenTmp, gridTmp;
    cullNan(_ycen, _grid, ycenTmp, gridTmp);
    
    PTR(Interpolate) intobj;
    try {
        intobj = makeInterpolate(ycenTmp, gridTmp, interpStyle);
    } catch(pex::exceptions::OutOfRangeError &e) {
        switch (undersampleStyle) {
          case THROW_EXCEPTION:
            LSST_EXCEPT_ADD(e, "setting _gridcolumns");
            throw;
          case REDUCE_INTERP_ORDER:
            {
                if (gridTmp.empty()) {
                    // Set the column to NaN.  We'll deal with this properly when interpolating in x
                    ycenTmp.push_back(0);
                    gridTmp.push_back(std::numeric_limits<double>::quiet_NaN());

                    intobj = makeInterpolate(ycenTmp, gridTmp, Interpolate::CONSTANT);
                    break;
                } else {
                    return _setGridColumns(lookupMaxInterpStyle(gridTmp.size()), undersampleStyle, iX, ypix);
                }
            }
          case INCREASE_NXNYSAMPLE:
            LSST_EXCEPT_ADD(e, "The BackgroundControl UndersampleStyle INCREASE_NXNYSAMPLE is not supported.");
            throw;
          default:
            LSST_EXCEPT_ADD(e, str(boost::format("The selected BackgroundControl "
                                                 "UndersampleStyle %d is not defined.") % undersampleStyle));
            throw;
        }
    } catch(ex::Exception &e) {
        LSST_EXCEPT_ADD(e, "setting _gridcolumns");
        throw;
    }
        
    for (int iY = 0; iY < height; ++iY) {
        _gridColumns[iX][iY] = intobj->interpolate(ypix[iY]);
    }
}

template<typename PixelT >

boost::shared_ptr< Approximate< PixelT > > lsst::afw::math::BackgroundMI::doGetApproximate ( ApproximateControl const &  actrl, UndersampleStyle const  undersampleStyle  ) const

private

Definition at line 418 of file BackgroundMI.cc.

{
    auto const localBBox = afw::geom::Box2I(afw::geom::Point2I(0, 0), _imgBBox.getDimensions());
    return makeApproximate(_xcen, _ycen, _statsImage, localBBox, actrl);
}

template<typename PixelT >

boost::shared_ptr< image::Image< PixelT > > lsst::afw::math::BackgroundMI::doGetImage ( geom::Box2I const &  bbox, Interpolate::Style const  interpStyle_, UndersampleStyle const  undersampleStyle  ) const

private

Definition at line 259 of file BackgroundMI.cc.

{
    if (!_imgBBox.contains(bbox)) {
        throw LSST_EXCEPT(ex::LengthError,
                          str(boost::format("BBox (%d:%d,%d:%d) out of range (%d:%d,%d:%d)") %
                              bbox.getMinX() % bbox.getMaxX() % bbox.getMinY() % bbox.getMaxY() %
                              _imgBBox.getMinX() % _imgBBox.getMaxX() %
                              _imgBBox.getMinY() % _imgBBox.getMaxY()));
    }
    int const nxSample = _statsImage.getWidth();
    int const nySample = _statsImage.getHeight();
    Interpolate::Style interpStyle = interpStyle_; // not const -- may be modified if REDUCE_INTERP_ORDER

    /*
     * Save the as-used interpStyle and undersampleStyle.
     *
     * N.b. The undersampleStyle may actually be overridden for some columns of the statsImage if they
     * have too few good values.  This doesn't prevent you reproducing the results of getImage() by
     * calling getImage(getInterpStyle(), getUndersampleStyle())
     */
    _asUsedInterpStyle = interpStyle;
    _asUsedUndersampleStyle = undersampleStyle;
    /*
     * Check if the requested nx,ny are sufficient for the requested interpolation style,
     * making suitable adjustments
     */
    bool const isXundersampled = (nxSample < lookupMinInterpPoints(interpStyle));
    bool const isYundersampled = (nySample < lookupMinInterpPoints(interpStyle));

    switch (undersampleStyle) {
      case THROW_EXCEPTION:
        if (isXundersampled && isYundersampled) {
            throw LSST_EXCEPT(ex::InvalidParameterError,
                              "nxSample and nySample have too few points for requested interpolation style.");
        } else if (isXundersampled) {
            throw LSST_EXCEPT(ex::InvalidParameterError,
                              "nxSample has too few points for requested interpolation style.");
        } else if (isYundersampled) {
            throw LSST_EXCEPT(ex::InvalidParameterError,
                              "nySample has too few points for requested interpolation style.");
        }
        break;
      case REDUCE_INTERP_ORDER:
        if (isXundersampled || isYundersampled) {
            Interpolate::Style const xStyle = lookupMaxInterpStyle(nxSample);
            Interpolate::Style const yStyle = lookupMaxInterpStyle(nySample);
            interpStyle = (nxSample < nySample) ? xStyle : yStyle;
            _asUsedInterpStyle = interpStyle;
        }
        break;
      case INCREASE_NXNYSAMPLE:
        if (isXundersampled || isYundersampled) {
            throw LSST_EXCEPT(ex::InvalidParameterError,
                              "The BackgroundControl UndersampleStyle INCREASE_NXNYSAMPLE is not supported.");
        }
        break;
      default:
        throw LSST_EXCEPT(ex::InvalidParameterError,
                          str(boost::format("The selected BackgroundControl "
                                            "UndersampleStyle %d is not defined.") % undersampleStyle));
    }

    // if we're approximating, don't bother with the rest of the interp-related work.  Return from here.
    if (_bctrl->getApproximateControl()->getStyle() != ApproximateControl::UNKNOWN) {
        return doGetApproximate<PixelT>(*_bctrl->getApproximateControl(), _asUsedUndersampleStyle)->getImage();
    }
    
    // =============================================================
    // --> We'll store nxSample fully-interpolated columns to interpolate the rows over
    // make a vector containing the y pixel coords for the column
    int const width = _imgBBox.getWidth();
    int const height = _imgBBox.getHeight();
    auto const bboxOff = bbox.getMin() - _imgBBox.getMin();

    std::vector<int> ypix(height);
    for (int iY = 0; iY < height; ++iY) {
        ypix[iY] = iY;
    }

    _gridColumns.resize(width);
    for (int iX = 0; iX < nxSample; ++iX) {
        _setGridColumns(interpStyle, undersampleStyle, iX, ypix);
    }

    // create a shared_ptr to put the background image in and return to caller
    // start with xy0 = 0 and set final xy0 later
    PTR(image::Image<PixelT>) bg =
        PTR(image::Image<PixelT>)(new image::Image<PixelT>(bbox.getDimensions()));

    // go through row by row
    // - interpolate on the gridcolumns that were pre-computed by the constructor
    // - copy the values to an ImageT to return to the caller.
    std::vector<double> xcenTmp, bgTmp;

    // N.b. There's no API to set defaultValue to other than NaN (due to issues with persistence
    // that I don't feel like fixing;  #2825).  If we want to address this, this is the place
    // to start, but note that NaN is treated specially -- it means, "Interpolate" so to allow
    // us to put a NaN into the outputs some changes will be needed
    double defaultValue = std::numeric_limits<double>::quiet_NaN();

    for (int y = 0, iY = bboxOff.getY(); y < bbox.getHeight(); ++y, ++iY) {
        // build an interp object for this row
        std::vector<double> bg_x(nxSample);
        for (int iX = 0; iX < nxSample; iX++) {
            bg_x[iX] = static_cast<double>(_gridColumns[iX][iY]);
        }
        cullNan(_xcen, bg_x, xcenTmp, bgTmp, defaultValue);

        PTR(Interpolate) intobj;
        try {
            intobj = makeInterpolate(xcenTmp, bgTmp, interpStyle);
        } catch(pex::exceptions::OutOfRangeError &e) {
            switch (undersampleStyle) {
              case THROW_EXCEPTION:
                LSST_EXCEPT_ADD(e, str(boost::format("Interpolating in y (iY = %d)") % iY));
                throw;
              case REDUCE_INTERP_ORDER:
                {
                    if (bgTmp.empty()) {
                        xcenTmp.push_back(0);
                        bgTmp.push_back(defaultValue);
                        
                        intobj = makeInterpolate(xcenTmp, bgTmp, Interpolate::CONSTANT);
                        break;
                    } else {
                        intobj = makeInterpolate(xcenTmp, bgTmp, lookupMaxInterpStyle(bgTmp.size()));
                    }
                }
                break;
              case INCREASE_NXNYSAMPLE:
                LSST_EXCEPT_ADD(e, "The BackgroundControl UndersampleStyle INCREASE_NXNYSAMPLE is not supported.");
                throw;
              default:
                LSST_EXCEPT_ADD(e, str(boost::format("The selected BackgroundControl "
                                                     "UndersampleStyle %d is not defined.") % undersampleStyle));
                throw;
            }
        } catch(ex::Exception &e) {
            LSST_EXCEPT_ADD(e, str(boost::format("Interpolating in y (iY = %d)") % iY));
            throw;
        }

        // fill the image with interpolated values
        for (int iX = bboxOff.getX(), x = 0; x < bbox.getWidth(); ++iX, ++x) {
            (*bg)(x, y) = static_cast<PixelT>(intobj->interpolate(iX));
        }
    }
    bg->setXY0(bbox.getMin());

    return bg;
}

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

Method to retrieve the background level at a pixel coord.

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.

Parameters

interpStyle	How to interpolate
x	x-pixel coordinate (column)
y	y-pixel coordinate (row)

Definition at line 231 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 {
        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;
    }
}

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

                                                    {
        return getPixel(_bctrl->getInterpStyle(), x, y);
    }

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

                                                                  {
        return _statsImage;
    }

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

virtual

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 208 of file BackgroundMI.cc.

{
    _statsImage += delta;
}

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

virtual

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 217 of file BackgroundMI.cc.

{
    _statsImage -= delta;
}

Member Data Documentation

std::vector<std::vector<double> > lsst::afw::math::BackgroundMI::_gridColumns

mutableprivate

Definition at line 435 of file Background.h.

lsst::afw::image::MaskedImage<InternalPixelT> lsst::afw::math::BackgroundMI::_statsImage

private

Definition at line 434 of file Background.h.

---

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

• /home/lsstsw/stack/Linux64/afw/11.0-2-g04d2804/include/lsst/afw/math/Background.h
• /home/lsstsw/stack/Linux64/afw/11.0-2-g04d2804/src/math/BackgroundMI.cc