#include <Convolve.h>

Inheritance diagram for lsst::afw::math::detail::KernelImagesForRegion:

Public Types
enum	Location { BOTTOM_LEFT, BOTTOM_RIGHT, TOP_LEFT, TOP_RIGHT }

typedef boost::shared_ptr < lsst::afw::math::Kernel const >	KernelConstPtr

typedef lsst::afw::image::Image < lsst::afw::math::Kernel::Pixel >	Image

typedef boost::shared_ptr< Image >	ImagePtr

typedef boost::shared_ptr < Image const >	ImageConstPtr

typedef boost::shared_ptr < KernelImagesForRegion const >	ConstPtr

typedef boost::shared_ptr < KernelImagesForRegion >	Ptr

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)

Public Types inherited from lsst::daf::base::Persistable
typedef boost::shared_ptr < Persistable >	Ptr

Public Member Functions
	KernelImagesForRegion (KernelConstPtr kernelPtr, lsst::afw::geom::Box2I const &bbox, lsst::afw::geom::Point2I const &xy0, bool doNormalize)

	KernelImagesForRegion (KernelConstPtr kernelPtr, lsst::afw::geom::Box2I const &bbox, lsst::afw::geom::Point2I const &xy0, bool doNormalize, ImagePtr bottomLeftImagePtr, ImagePtr bottomRightImagePtr, ImagePtr topLeftImagePtr, ImagePtr topRightImagePtr)

lsst::afw::geom::Box2I	getBBox () const

lsst::afw::geom::Point2I	getXY0 () const

bool	getDoNormalize () const

ImagePtr	getImage (Location location) const

KernelConstPtr	getKernel () const

lsst::afw::geom::Point2I	getPixelIndex (Location location) const

bool	computeNextRow (RowOfKernelImagesForRegion &regionRow) const
	Compute next row of subregions. More...

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...

Public Member Functions inherited from lsst::daf::base::Persistable
	Persistable (void)

virtual	~Persistable (void)

template<class Archive >
void	serialize (Archive &, unsigned int const)

Static Public Member Functions
static int	getMinInterpolationSize ()

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...

Private Types
typedef std::vector< Location >	LocationList

Private Member Functions
void	_computeImage (Location location) const

void	_insertImage (Location location, ImagePtr imagePtr) const

void	_moveUp (bool isFirst, int newHeight)
	Move the region up one segment. More...

Static Private Member Functions
static int	_computeNextSubregionLength (int length, int nDivisions)

static std::vector< int >	_computeSubregionLengths (int length, int nDivisions)

Private Attributes
KernelConstPtr	_kernelPtr

lsst::afw::geom::Box2I	_bbox

lsst::afw::geom::Point2I	_xy0

bool	_doNormalize

std::vector< ImagePtr >	_imagePtrList

Static Private Attributes
static int const	_MinInterpolationSize = 10

Detailed Description

A collection of Kernel images for special locations on a rectangular region of an image

See the Location enum for a list of those special locations.

Warning: The kernel images along the top and right edges are computed one row or column past the bounding box. This allows abutting KernelImagesForRegion to share corner and edge kernel images, which is useful when dividing a KernelImagesForRegion into subregions.; The bounding box for the region applies to the parent image.

This is a low-level helper class for recursive convolving with interpolation. Many of these objects may be created during a convolution, and many will share kernel images. It uses shared pointers to kernels and kernel images for increased speed and decreased memory usage (at the expense of safety). Note that null pointers are NOT acceptable for the constructors!

Also note that it uses lazy evaluation: images are computed when they are wanted.

Definition at line 111 of file Convolve.h.

Member Typedef Documentation

typedef boost::shared_ptr< KernelImagesForRegion const> lsst::afw::math::detail::KernelImagesForRegion::ConstPtr

Definition at line 120 of file Convolve.h.

typedef lsst::afw::image::Image<lsst::afw::math::Kernel::Pixel> lsst::afw::math::detail::KernelImagesForRegion::Image

Definition at line 117 of file Convolve.h.

typedef boost::shared_ptr< Image const> lsst::afw::math::detail::KernelImagesForRegion::ImageConstPtr

Definition at line 119 of file Convolve.h.

typedef boost::shared_ptr< Image > lsst::afw::math::detail::KernelImagesForRegion::ImagePtr

Definition at line 118 of file Convolve.h.

typedef boost::shared_ptr< lsst::afw::math::Kernel const> lsst::afw::math::detail::KernelImagesForRegion::KernelConstPtr

Definition at line 116 of file Convolve.h.

typedef std::vector<Location> lsst::afw::math::detail::KernelImagesForRegion::LocationList

private

Definition at line 178 of file Convolve.h.

typedef boost::shared_ptr< KernelImagesForRegion > lsst::afw::math::detail::KernelImagesForRegion::Ptr

Definition at line 121 of file Convolve.h.

Member Enumeration Documentation

enum lsst::afw::math::detail::KernelImagesForRegion::Location

locations of various points in the region

RIGHT and TOP are one column/row beyond the region's bounding box. Thus adjacent regions share corner images.

The posiitions are: BOTTOM_LEFT, BOTTOM_RIGHT, TOP_LEFT, TOP_RIGHT

These locations always refer to the center of a pixel. Thus if the region has an odd size along an axis (so that the span to the top and right, which are one beyond, is even), the middle pixel will be 1/2 pixel off from the true center along that axis (in an unspecified direction).

Enumerator
BOTTOM_LEFT
BOTTOM_RIGHT
TOP_LEFT
TOP_RIGHT

Definition at line 136 of file Convolve.h.

                       {
             BOTTOM_LEFT, BOTTOM_RIGHT, TOP_LEFT, TOP_RIGHT
         };

Constructor & Destructor Documentation

lsst::afw::math::detail::KernelImagesForRegion::KernelImagesForRegion	(	KernelConstPtr	kernelPtr,
		lsst::afw::geom::Box2I const &	bbox,
		lsst::afw::geom::Point2I const &	xy0,
		bool	doNormalize
	)

Construct a KernelImagesForRegion

Exceptions

lsst::pex::exceptions::InvalidParameterError if kernelPtr is null

Parameters

kernelPtr	kernel
bbox	bounding box of region of an image for which we want to compute kernel images (inclusive and relative to parent image)
xy0	xy0 of image for which we want to compute kernel images
doNormalize	normalize the kernel images?

Definition at line 59 of file KernelImagesForRegion.cc.

 :
     lsst::daf::base::Citizen(typeid(this)),
     _kernelPtr(kernelPtr),
     _bbox(bbox),
     _xy0(xy0),
     _doNormalize(doNormalize),
     _imagePtrList(4)
 {
     if (!_kernelPtr) {
         throw LSST_EXCEPT(pexExcept::InvalidParameterError, "kernelPtr is null");
     }
     pexLog::TTrace<6>("lsst.afw.math.convolve",
     "KernelImagesForRegion(bbox(minimum=(%d, %d), extent=(%d, %d)), xy0=(%d, %d), doNormalize=%d, images...)",
        _bbox.getMinX(), _bbox.getMinY(), _bbox.getWidth(), _bbox.getHeight(), _xy0[0], _xy0[1], _doNormalize);
 }

lsst::afw::math::detail::KernelImagesForRegion::KernelImagesForRegion	(	KernelConstPtr	kernelPtr,
		lsst::afw::geom::Box2I const &	bbox,
		lsst::afw::geom::Point2I const &	xy0,
		bool	doNormalize,
		ImagePtr	bottomLeftImagePtr,
		ImagePtr	bottomRightImagePtr,
		ImagePtr	topLeftImagePtr,
		ImagePtr	topRightImagePtr
	)

Construct a KernelImagesForRegion with some or all corner images

Null corner image pointers are ignored.

Warning: : if any images are incorrect you will get a mess.

Exceptions

lsst::pex::exceptions::InvalidParameterError	if kernelPtr is null
lsst::pex::exceptions::InvalidParameterError	if an image has the wrong dimensions

Parameters

kernelPtr	kernel
bbox	bounding box of region of an image for which we want to compute kernel images (inclusive and relative to parent image)
xy0	xy0 of image
doNormalize	normalize the kernel images?
bottomLeftImagePtr	kernel image and sum at bottom left of region
bottomRightImagePtr	kernel image and sum at bottom right of region
topLeftImagePtr	kernel image and sum at top left of region
topRightImagePtr	kernel image and sum at top right of region

Definition at line 92 of file KernelImagesForRegion.cc.

 :
     lsst::daf::base::Citizen(typeid(this)),
     _kernelPtr(kernelPtr),
     _bbox(bbox),
     _xy0(xy0),
     _doNormalize(doNormalize),
     _imagePtrList(4)
 {
     if (!_kernelPtr) {
         throw LSST_EXCEPT(pexExcept::InvalidParameterError, "kernelPtr is null");
     }
     _insertImage(BOTTOM_LEFT, bottomLeftImagePtr);
     _insertImage(BOTTOM_RIGHT, bottomRightImagePtr);
     _insertImage(TOP_LEFT, topLeftImagePtr);
     _insertImage(TOP_RIGHT, topRightImagePtr);
     pexLog::TTrace<6>("lsst.afw.math.convolve",
     "KernelImagesForRegion(bbox(minimum=(%d, %d), extent=(%d, %d)), xy0=(%d, %d), doNormalize=%d, images...)",
        _bbox.getMinX(), _bbox.getMinY(), _bbox.getWidth(), _bbox.getHeight(), _xy0[0], _xy0[1], _doNormalize);
 }

Member Function Documentation

void lsst::afw::math::detail::KernelImagesForRegion::_computeImage ( Location location ) const

private

Compute image at a particular location

Exceptions

lsst::pex::exceptions::NotFoundError if there is no pointer at that location

Definition at line 250 of file KernelImagesForRegion.cc.

                                                                            {
     ImagePtr imagePtr = _imagePtrList[location];
     if (!imagePtr) {
         std::ostringstream os;
         os << "Null imagePtr at location " << location;
         throw LSST_EXCEPT(pexExcept::NotFoundError, os.str());
     }
 
     afwGeom::Point2I pixelIndex = getPixelIndex(location);
     _kernelPtr->computeImage(
         *imagePtr,
         _doNormalize,
         afwImage::indexToPosition(pixelIndex.getX() + _xy0[0]),
         afwImage::indexToPosition(pixelIndex.getY() + _xy0[1]));
 }

int lsst::afw::math::detail::KernelImagesForRegion::_computeNextSubregionLength	(	int	length,
		int	nDivisions
	)

inlinestaticprivate

Compute length of next subregion if the region is to be divided into pieces of approximately equal length.

Returns: length of next subregion

Warning: : no range checking

Parameters

length	length of region
nDivisions	number of divisions of region

Definition at line 304 of file Convolve.h.

 {
     return static_cast<int>(std::floor(0.5 +
         (static_cast<double>(length) / static_cast<double>(nDivisions))));
 }

std::vector< int > lsst::afw::math::detail::KernelImagesForRegion::_computeSubregionLengths	(	int	length,
		int	nDivisions
	)

staticprivate

Compute length of each subregion for a region divided into nDivisions pieces of approximately equal length.

Returns: a list of subspan lengths

Exceptions

lsst::pex::exceptions::InvalidParameterError if nDivisions >= length

Parameters

length	length of region
nDivisions	number of divisions of region

Definition at line 274 of file KernelImagesForRegion.cc.

 {
     if ((nDivisions > length) || (nDivisions < 1)) {
         std::ostringstream os;
         os << "nDivisions = " << nDivisions << " not in range [1, " << length << " = length]";
         throw LSST_EXCEPT(pexExcept::InvalidParameterError, os.str());
     }
     std::vector<int> regionLengths;
     int remLength = length;
     for (int remNDiv = nDivisions; remNDiv > 0; --remNDiv) {
         int subLength = _computeNextSubregionLength(remLength, remNDiv);
         if (subLength < 1) {
             std::ostringstream os;
             os << "Bug! _computeSubregionLengths(length=" << length << ", nDivisions=" << nDivisions <<
                 ") computed sublength = " << subLength << " < 0; remLength = " << remLength;
             throw LSST_EXCEPT(pexExcept::RuntimeError, os.str());
         }
         regionLengths.push_back(subLength);
         remLength -= subLength;
     }
     return regionLengths;
 }

void lsst::afw::math::detail::KernelImagesForRegion::_insertImage	(	Location	location,
		ImagePtr	imagePtr
	)		const

inlineprivate

Insert an image in the cache.

Exceptions

lsst::pex::exceptions::InvalidParameterError	if image pointer is null
lsst::pex::exceptions::InvalidParameterError	if image has the wrong dimensions

Parameters

location	location at which to insert image
imagePtr	image to insert

Definition at line 318 of file Convolve.h.

       {
     if (imagePtr) {
         if (_kernelPtr->getDimensions() != imagePtr->getDimensions()) {
             std::ostringstream os;
             os << "image dimensions = ( " 
                 << imagePtr->getWidth() << ", " << imagePtr->getHeight()
                 << ") != (" << _kernelPtr->getWidth() << ", " << _kernelPtr->getHeight()
                 << ") = kernel dimensions";
             throw LSST_EXCEPT(lsst::pex::exceptions::InvalidParameterError, os.str());
         }
         _imagePtrList[location] = imagePtr;
     }
 }

void lsst::afw::math::detail::KernelImagesForRegion::_moveUp	(	bool	isFirst,
		int	newHeight
	)

private

Move the region up one segment.

To avoid reallocating memory for kernel images, swap the top and bottom kernel image pointers and recompute the top images. Actually, only does this to the right-hande images if isFirst is false since it assumes the left images were already handled.

Intended to support computeNextRow; as such assumes that a list of adjacent regions will be moved, left to right.

Parameters

isFirst	true if the first region in a row (or the only region you are moving)
newHeight	new height of region

Definition at line 309 of file KernelImagesForRegion.cc.

 {
     // move bbox up (this must be done before recomputing the top kernel images)
     _bbox = afwGeom::Box2I(
         afwGeom::Point2I(_bbox.getMinX(), _bbox.getMaxY() + 1),
         afwGeom::Extent2I(_bbox.getWidth(), newHeight));
 
     // swap top and bottom image pointers
     _imagePtrList[BOTTOM_RIGHT].swap(_imagePtrList[TOP_RIGHT]);
     _imagePtrList[BOTTOM_LEFT].swap(_imagePtrList[TOP_LEFT]);
 
     // recompute top right, and if the first image also recompute top left
     _computeImage(TOP_RIGHT);
     if (isFirst) {
         _computeImage(TOP_LEFT);
     }
 }

bool lsst::afw::math::detail::KernelImagesForRegion::computeNextRow ( RowOfKernelImagesForRegion & regionRow ) const

Compute next row of subregions.

For the first row call with a new RowOfKernelImagesForRegion (with the desired number of columns and rows). Every subequent call updates the data in the RowOfKernelImagesForRegion.

Returns: true if a new row was computed, false if supplied RowOfKernelImagesForRegion is for the last row.

Parameters

regionRow RowOfKernelImagesForRegion object

Definition at line 177 of file KernelImagesForRegion.cc.

       {
     if (regionRow.isLastRow()) {
         return false;
     }
     
     bool hasData = regionRow.hasData();
     int startY;
     if (hasData) {
         startY = regionRow.front()->getBBox().getMaxY() + 1;
     } else {
         startY = this->_bbox.getMinY();
     }
 
     int yInd = regionRow.incrYInd();
     int remHeight = 1 + this->_bbox.getMaxY() - startY;
     int remYDiv = regionRow.getNY() - yInd;
     int height = _computeNextSubregionLength(remHeight, remYDiv);
     
     if (hasData) {
         // Move each region up one segment
         bool isFirst = true;
         for (RowOfKernelImagesForRegion::Iterator rgnIter = regionRow.begin(), rgnEnd = regionRow.end();
             rgnIter != rgnEnd; ++rgnIter) {
             (*rgnIter)->_moveUp(isFirst, height);
             isFirst = false;
         }
 
     } else {
         ImagePtr blImagePtr = getImage(BOTTOM_LEFT);
         ImagePtr brImagePtr;
         ImagePtr tlImagePtr;
         ImagePtr const trImageNullPtr;
 
         afwGeom::Point2I blCorner = afwGeom::Point2I(this->_bbox.getMinX(), startY);
 
         int remWidth = this->_bbox.getWidth();
         int remXDiv = regionRow.getNX();
         for (RowOfKernelImagesForRegion::Iterator rgnIter = regionRow.begin(), rgnEnd = regionRow.end();
             rgnIter != rgnEnd; ++rgnIter) {
             int width = _computeNextSubregionLength(remWidth, remXDiv);
             --remXDiv;
             remWidth -= width;
             
             KernelImagesForRegion::Ptr regionPtr(new KernelImagesForRegion(
                 _kernelPtr,
                 afwGeom::Box2I(blCorner, afwGeom::Extent2I(width, height)),
                 _xy0,
                 _doNormalize,
                 blImagePtr,
                 brImagePtr,
                 tlImagePtr,
                 trImageNullPtr));
             *rgnIter = regionPtr;
             
             if (!tlImagePtr) {
                 regionPtr->getImage(TOP_LEFT);
             }
             
             blCorner += afwGeom::Extent2I(width, 0);
             blImagePtr = regionPtr->getImage(BOTTOM_RIGHT);
             tlImagePtr = regionPtr->getImage(TOP_RIGHT);
         }
     }
     return true;
 }

lsst::afw::geom::Box2I lsst::afw::math::detail::KernelImagesForRegion::getBBox ( ) const

inline

Get the bounding box for the region

Definition at line 158 of file Convolve.h.

158 { return _bbox; };

lsst::afw::math::detail::KernelImagesForRegion::_bbox

lsst::afw::geom::Box2I _bbox

Definition: Convolve.h:192

bool lsst::afw::math::detail::KernelImagesForRegion::getDoNormalize ( ) const

inline

Get the doNormalize parameter

Definition at line 166 of file Convolve.h.

166 { return _doNormalize; };

lsst::afw::math::detail::KernelImagesForRegion::_doNormalize

bool _doNormalize

Definition: Convolve.h:194

mathDetail::KernelImagesForRegion::ImagePtr lsst::afw::math::detail::KernelImagesForRegion::getImage ( Location location ) const

Return the image and sum at the specified location

If the image has not yet been computed, it is computed at this time.

Parameters

location location of image

Definition at line 128 of file KernelImagesForRegion.cc.

       {
     if (_imagePtrList[location]) {
         return _imagePtrList[location];
     }
 
     ImagePtr imagePtr(new Image(_kernelPtr->getDimensions()));
     _imagePtrList[location] = imagePtr;
     _computeImage(location);
     return imagePtr;
 }

KernelConstPtr lsst::afw::math::detail::KernelImagesForRegion::getKernel ( ) const

inline

Get the kernel (as a shared pointer to const)

Definition at line 171 of file Convolve.h.

171 { return _kernelPtr; };

lsst::afw::math::detail::KernelImagesForRegion::_kernelPtr

KernelConstPtr _kernelPtr

Definition: Convolve.h:191

static int lsst::afw::math::detail::KernelImagesForRegion::getMinInterpolationSize ( )

inlinestatic

Get the minInterpolationSize class constant

Definition at line 178 of file Convolve.h.

178 { return _MinInterpolationSize; };

lsst::afw::math::detail::KernelImagesForRegion::_MinInterpolationSize

static int const _MinInterpolationSize

Definition: Convolve.h:197

lsst::afw::geom::Point2I lsst::afw::math::detail::KernelImagesForRegion::getPixelIndex ( Location location ) const

Compute pixel index of a given location, relative to the parent image (thus offset by bottom left corner of bounding box)

Parameters

location location for which to return pixel index

Definition at line 145 of file KernelImagesForRegion.cc.

       {
     switch (location) {
         case BOTTOM_LEFT:
             return _bbox.getMin();
             break; // paranoia
         case BOTTOM_RIGHT:
             return afwGeom::Point2I(_bbox.getMaxX() + 1, _bbox.getMinY());
             break; // paranoia
         case TOP_LEFT:
             return afwGeom::Point2I(_bbox.getMinX(), _bbox.getMaxY() + 1);
             break; // paranoia
         case TOP_RIGHT:
             return afwGeom::Point2I(_bbox.getMaxX() + 1, _bbox.getMaxY() + 1);
             break; // paranoia
         default: {
             std::ostringstream os;
             os << "Bug: unhandled location = " << location;
             throw LSST_EXCEPT(pexExcept::InvalidParameterError, os.str());
         }
     }
 }

lsst::afw::geom::Point2I lsst::afw::math::detail::KernelImagesForRegion::getXY0 ( ) const

inline

Get xy0 of the image

Definition at line 162 of file Convolve.h.

162 { return _xy0; };

lsst::afw::math::detail::KernelImagesForRegion::_xy0

lsst::afw::geom::Point2I _xy0

Definition: Convolve.h:193

Member Data Documentation

lsst::afw::geom::Box2I lsst::afw::math::detail::KernelImagesForRegion::_bbox

private

Definition at line 192 of file Convolve.h.

bool lsst::afw::math::detail::KernelImagesForRegion::_doNormalize

private

Definition at line 194 of file Convolve.h.

std::vector<ImagePtr> lsst::afw::math::detail::KernelImagesForRegion::_imagePtrList

mutableprivate

Definition at line 195 of file Convolve.h.

KernelConstPtr lsst::afw::math::detail::KernelImagesForRegion::_kernelPtr

private

Definition at line 191 of file Convolve.h.

int const lsst::afw::math::detail::KernelImagesForRegion::_MinInterpolationSize = 10

staticprivate

Definition at line 197 of file Convolve.h.

lsst::afw::geom::Point2I lsst::afw::math::detail::KernelImagesForRegion::_xy0

private

Definition at line 193 of file Convolve.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/detail/Convolve.h
/home/lsstsw/stack/Linux64/afw/11.0-2-g04d2804/src/math/detail/KernelImagesForRegion.cc

Public Types

Public Member Functions

Static Public Member Functions

Private Types

Private Member Functions

Static Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation