lsst::geom::IntervalI Class Reference

A 1-d integer coordinate range. More...

#include <Interval.h>

Public Types
enum class	EdgeHandlingEnum { EXPAND , SHRINK }
	Enum used to indicate how to handle conversions from floating-point to integer intervals. More...
using	Element = int

Public Member Functions
	IntervalI () noexcept
	Construct an empty interval.
	IntervalI (IntervalD const &other, EdgeHandlingEnum edgeHandling=EdgeHandlingEnum::EXPAND)
	Construct an integer interval from a floating-point interval.
	IntervalI (IntervalI const &) noexcept=default
	Standard copy constructor.
	IntervalI (IntervalI &&) noexcept=default
	Standard move constructor.
	~IntervalI () noexcept=default
void	swap (IntervalI &other) noexcept
IntervalI &	operator= (IntervalI const &) noexcept=default
	Standard copy assignment operator.
IntervalI &	operator= (IntervalI &&) noexcept=default
	Standard move assignment operatior.
Min/Max Accessors
Return the minimum and maximum coordinates of the interval (inclusive).
Element	getMin () const noexcept
Element	getMax () const noexcept
Begin/End Accessors
Return begin (inclusive) and end (exclusive) coordinates for the interval.
Element	getBegin () const noexcept
Element	getEnd () const noexcept

Static Public Member Functions
template<typename Iter >
static IntervalI	fromSpannedPoints (Iter first, Iter last)
	Construct an interval that contains all of the given points.
static IntervalI	fromSpannedPoints (std::vector< Element > const &elements)
	Construct an interval that contains all of the given points.
static IntervalI	fromSpannedPoints (ndarray::Array< Element const, 1 > const &elements)
static IntervalI	fromMinMax (Element min, Element max)
	Construct an interval from its lower and upper bounds.
static IntervalI	fromMinSize (Element min, Element size)
	Construct an interval from its lower bound and size.
static IntervalI	fromMaxSize (Element max, Element size)
	Construct an interval from its upper bound and size.
static IntervalI	fromCenterSize (double center, Element size)
	Create an interval centered as closely as possible on a particular point.

Size Accessors
Return the size of the interval in pixels.
Element	getSize () const noexcept
	Return slice to extract the interval's region from an ndarray::Array.
ndarray::View< boost::fusion::vector1< ndarray::index::Range > >	getSlice () const
	Return slice to extract the interval's region from an ndarray::Array.
bool	isEmpty () const noexcept
	Return true if the interval contains no points.
bool	contains (Element point) const noexcept
	Return true if the interval contains the point.
bool	contains (IntervalI const &other) const noexcept
	Return true if all points contained by other are also contained by this.
bool	overlaps (IntervalI const &other) const noexcept
	Return true if there are any points in both this and other.
bool	intersects (IntervalI const &other) const noexcept
	Return slice to extract the interval's region from an ndarray::Array.
bool	isDisjointFrom (IntervalI const &other) const noexcept
	Return true if there are no points in both this and other.
IntervalI	dilatedBy (Element buffer) const
	Increase the size of the interval by the given amount in both directions (returning a new object).
IntervalI	erodedBy (Element buffer) const
	Decrease the size of the interval by the given amount in both directions (returning a new object).
IntervalI	shiftedBy (Element offset) const
	Shift the position of the interval by the given offset (returning a new object).)
IntervalI	reflectedAbout (Element point) const
	Reflect an interval about a point (returning a new object).
IntervalI	expandedTo (Element other) const
	Expand an interval to ensure that contains(other) is true (returning a new object).
IntervalI	expandedTo (IntervalI const &other) const
	Return slice to extract the interval's region from an ndarray::Array.
IntervalI	clippedTo (IntervalI const &other) const noexcept
	Shrink an interval to ensure that it is contained by other (returning a new)
bool	operator== (IntervalI const &other) const noexcept
	Compare two intervals for equality.
bool	operator!= (IntervalI const &other) const noexcept
	Compare two intervals for equality.
std::size_t	hash_value () const noexcept
	Return a hash of this object.
std::string	toString () const
	Return slice to extract the interval's region from an ndarray::Array.

Detailed Description

A 1-d integer coordinate range.

IntervalI is an inclusive range that represents region of pixels. An IntervalI never has negative size; the empty interval is defined to have zero size, and is treated as though it does not have a well-defined position (regardless of the return value of getMin() or getMax() for an empty interval).

All IntervalI methods that return a new instance (and are not marked noexcept) throw OverflowError if the lower bound, upper bound, or the size would be too large to fit in int.

Definition at line 50 of file Interval.h.

Member Typedef Documentation

Element

using lsst::geom::IntervalI::Element = int

Definition at line 52 of file Interval.h.

Member Enumeration Documentation

EdgeHandlingEnum

enum class lsst::geom::IntervalI::EdgeHandlingEnum

strong

Enum used to indicate how to handle conversions from floating-point to integer intervals.

Note that the floating point bounds for some pixel x in an integer interval are [x - 0.5, x + 0.5] (because the pixel has unit size, and integer coordinates correspond to the centers of pixels). This means interval conversions involve more than just rounding the bounds inward or outward.

Enumerator
EXPAND	Include all pixels that overlap the floating-point interval at all.
SHRINK	Include only pixels that are wholly contained by the floating-point interval.

Definition at line 64 of file Interval.h.

                                {
        EXPAND,
        SHRINK
    };

Constructor & Destructor Documentation

IntervalI() [1/4]

lsst::geom::IntervalI::IntervalI ( )

inlinenoexcept

Construct an empty interval.

Definition at line 77 of file Interval.h.

: _min(0), _size(0) {}

IntervalI() [2/4]

lsst::geom::IntervalI::IntervalI ( IntervalD const & other, EdgeHandlingEnum edgeHandling = EdgeHandlingEnum::EXPAND )

explicit

Construct an integer interval from a floating-point interval.

Floating-point to integer interval conversion is based on the concept that a pixel is not an infinitesimal point but rather a square of unit size centered on integer-valued coordinates. Converting a floating-point interval to an integer interval thus requires a choice on how to handle pixels which are only partially contained by the input floating-point interval.

Parameters

[in]	other	A floating-point interval to convert.
[in]	edgeHandling	If EXPAND, the integer interval will contain any pixels that overlap the floating-point interval. If SHRINK, the integer interval will contain only pixels completely contained by the floating-point interval.

Exceptions

lsst::pex::exceptions::InvalidParameterError	Thrown if other is not finite.
lsst::pex::exceptions::LogicError	Thrown if an invalid enum value is passed.

Definition at line 87 of file Interval.cc.

                                                                          : _min(), _size() {
    if (other.isEmpty()) {
        *this = IntervalI();
        return;
    }
    if (!std::isfinite(other.getMin()) || !std::isfinite(other.getMax())) {
        throw LSST_EXCEPT(pex::exceptions::InvalidParameterError,
                          "Cannot convert non-finite IntervalD to IntervalI");
    }
    BigElement min, max;
    switch (edgeHandling) {
        case EdgeHandlingEnum::EXPAND:
            min = static_cast<BigElement>(std::ceil(other.getMin() - 0.5));
            max = static_cast<BigElement>(std::floor(other.getMax() + 0.5));
            break;
        case EdgeHandlingEnum::SHRINK:
            min = static_cast<BigElement>(std::ceil(other.getMin() + 0.5));
            max = static_cast<BigElement>(std::floor(other.getMax() - 0.5));
            break;
        default:
            throw pex::exceptions::LogicError("Invalid enum value.");
    }
    *this = _fromMinMaxChecked(min, max);
}

IntervalI() [3/4]

lsst::geom::IntervalI::IntervalI ( IntervalI const & )

defaultnoexcept

Standard copy constructor.

IntervalI() [4/4]

lsst::geom::IntervalI::IntervalI ( IntervalI && )

defaultnoexcept

Standard move constructor.

~IntervalI()

lsst::geom::IntervalI::~IntervalI ( )

defaultnoexcept

Member Function Documentation

clippedTo()

IntervalI lsst::geom::IntervalI::clippedTo ( IntervalI const & other ) const

noexcept

Shrink an interval to ensure that it is contained by other (returning a new)

In particular, if other and this interval do not overlap, the returned interval will be empty.

Definition at line 186 of file Interval.cc.

                                                                    {
    if (isEmpty() || other.isEmpty()) {
        return IntervalI();
    }
    return fromMinMax(std::max(getMin(), other.getMin()), std::min(getMax(), other.getMax()));
}

contains() [1/2]

bool lsst::geom::IntervalI::contains ( Element point ) const

noexcept

Return true if the interval contains the point.

Definition at line 116 of file Interval.cc.

                                                     {
    // The case where this->isEmpty() is handled implicitly by the invariant
    // that empty intervals have max < min.
    return point >= this->getMin() && point <= this->getMax();
}

contains() [2/2]

bool lsst::geom::IntervalI::contains ( IntervalI const & other ) const

noexcept

Return true if all points contained by other are also contained by this.

An empty interval is contained by every other interval, including other empty intervals.

Definition at line 122 of file Interval.cc.

                                                              {
    // The case where this->isEmpty() is handled implicitly by the invariant
    // that empty intervals have max < min.
    return other.isEmpty() || (other.getMin() >= this->getMin() && other.getMax() <= this->getMax());
}

dilatedBy()

IntervalI lsst::geom::IntervalI::dilatedBy

(

Element

buffer

)

const

Increase the size of the interval by the given amount in both directions (returning a new object).

If buffer is negative, this is equivalent to eroding by -buffer.

If the final size of the interval is less than or equal to zero the new interval will be empty.

Empty intervals remain empty after dilation.

Definition at line 137 of file Interval.cc.

                                                   {
    if (isEmpty()) {
        return IntervalI();
    }
    BigElement min = static_cast<BigElement>(getMin()) - buffer;
    BigElement max = static_cast<BigElement>(getMax()) + buffer;
    return _fromMinMaxChecked(min, max);
}

erodedBy()

IntervalI lsst::geom::IntervalI::erodedBy ( Element buffer ) const

inline

Decrease the size of the interval by the given amount in both directions (returning a new object).

If buffer is negative, this is equivalent to dilating by -buffer.

If the final size of the interval is less than or equal to zero the new interval will be empty.

Empty intervals remain empty after erosion.

Definition at line 315 of file Interval.h.

{ return dilatedBy(-buffer); }

expandedTo() [1/2]

IntervalI lsst::geom::IntervalI::expandedTo

(

Element

other

)

const

Expand an interval to ensure that contains(other) is true (returning a new object).

Expanding an empty interval with a single point yields an interval with size=1 at that point; expanding an empty interval with a second interval is equivalent to assignment.

Definition at line 166 of file Interval.cc.

                                                   {
    if (isEmpty()) {
        return IntervalI(point, 1);
    }
    return _fromMinMaxChecked(std::min(static_cast<BigElement>(point), static_cast<BigElement>(getMin())),
                              std::max(static_cast<BigElement>(point), static_cast<BigElement>(getMax())));
}

expandedTo() [2/2]

IntervalI lsst::geom::IntervalI::expandedTo

(

IntervalI const &

other

)

const

Return slice to extract the interval's region from an ndarray::Array.

For example:

auto array = ndarray::copy(ndarray::arange(5);
auto interval = IntervalI::fromMinMax(2, 4);
auto subarray = array[interval.getSlice()];

Definition at line 174 of file Interval.cc.

                                                            {
    if (other.isEmpty()) {
        return *this;
    }
    if (this->isEmpty()) {
        return other;
    }
    return _fromMinMaxChecked(
            std::min(static_cast<BigElement>(other.getMin()), static_cast<BigElement>(getMin())),
            std::max(static_cast<BigElement>(other.getMax()), static_cast<BigElement>(getMax())));
}

fromCenterSize()

IntervalI lsst::geom::IntervalI::fromCenterSize ( double center, Element size )

static

Create an interval centered as closely as possible on a particular point.

Parameters

center	The desired center of the interval.
size	Number of pixels in interval. Nonpositive values will produce an empty interval.

Returns

if size is positive, an interval with size size; if size is zero or negative, an empty interval. If the returned interval is not empty, its center shall be within half a pixel of center.

Exceptions

lsst::pex::exceptions::OverflowError	Thrown if the resulting interval would overflow.
lsst::pex::exceptions::InvalidParameterError	Thrown if center is not finite and size is positive.

Definition at line 75 of file Interval.cc.

                                                               {
    if (size <= 0) {
        return IntervalI();
    }
    double min = center - 0.5 * size;
    // compensate for IntervalI's coordinate conventions (where max = min + size - 1)
    min += 0.5;
    checkForOverflow(min, "minimum");
    checkForOverflow(min + size - 1, "maximum");
    return IntervalI(static_cast<BigElement>(min), size);
}

fromMaxSize()

IntervalI lsst::geom::IntervalI::fromMaxSize ( Element max, Element size )

static

Construct an interval from its upper bound and size.

Parameters

[in]	max	Maximum coordinate (inclusive).
[in]	size	Number of pixels in interval. Nonpositive values will produce an empty interval.

Exceptions

lsst::pex::exceptions::OverflowError

Thrown if the resulting interval would overflow.

Definition at line 66 of file Interval.cc.

                                                          {
    if (size <= 0) {
        return IntervalI();
    }
    BigElement min = static_cast<BigElement>(max) - static_cast<BigElement>(size) + 1;
    checkForOverflow(min, "minimum");
    return IntervalI(static_cast<Element>(min), size);
}

fromMinMax()

IntervalI lsst::geom::IntervalI::fromMinMax ( Element min, Element max )

static

Construct an interval from its lower and upper bounds.

If min > max, the resulting interval is empty.

Parameters

[in]	min	Minimum coordinate (inclusive).
[in]	max	Maximum coordinate (inclusive).

Exceptions

lsst::pex::exceptions::OverflowError

Thrown if the resulting interval would overflow.

Definition at line 53 of file Interval.cc.

                                                        {
    return _fromMinMaxChecked(static_cast<BigElement>(min), static_cast<BigElement>(max));
}

fromMinSize()

IntervalI lsst::geom::IntervalI::fromMinSize ( Element min, Element size )

static

Construct an interval from its lower bound and size.

Parameters

[in]	min	Minimum coordinate (inclusive).
[in]	size	Number of pixels in interval. Nonpositive values will produce an empty interval.

Exceptions

lsst::pex::exceptions::OverflowError

Thrown if the resulting interval would overflow.

Definition at line 57 of file Interval.cc.

                                                          {
    if (size <= 0) {
        return IntervalI();
    }
    BigElement max = static_cast<BigElement>(min) + static_cast<BigElement>(size) - 1;
    checkForOverflow(max, "maximum");
    return IntervalI(min, size);
}

fromSpannedPoints() [1/3]

template<typename Iter >

static IntervalI lsst::geom::IntervalI::fromSpannedPoints ( Iter first, Iter last )

inlinestatic

Construct an interval that contains all of the given points.

Parameters

[in]	first	Iterator to the beginning of a sequence of integers.
[in]	last	Iterator to one-past-the-end of a sequence of integers.

An empty interval is returned if first == last.

Exceptions

lsst::pex::exceptions::OverflowError

Thrown if the resulting interval would overflow.

Definition at line 92 of file Interval.h.

                                                              {
        IntervalI result;
        for (auto i = first; i != last; ++i) {
            result = result.expandedTo(*i);
        }
        return result;
    }

fromSpannedPoints() [2/3]

static IntervalI lsst::geom::IntervalI::fromSpannedPoints ( ndarray::Array< Element const, 1 > const & elements )

inlinestatic

Definition at line 115 of file Interval.h.

                                                                                       {
        return fromSpannedPoints(elements.begin(), elements.end());
    }

fromSpannedPoints() [3/3]

static IntervalI lsst::geom::IntervalI::fromSpannedPoints ( std::vector< Element > const & elements )

inlinestatic

Construct an interval that contains all of the given points.

Parameters

[in]

elements

Points (integer values) to include in the interval.

An empty interval is returned if the given container has no elements.

Exceptions

lsst::pex::exceptions::OverflowError

Thrown if the resulting interval would overflow.

Definition at line 112 of file Interval.h.

                                                                           {
        return fromSpannedPoints(elements.begin(), elements.end());
    }

getBegin()

Element lsst::geom::IntervalI::getBegin ( ) const

inlinenoexcept

Definition at line 238 of file Interval.h.

{ return _min; }

getEnd()

Element lsst::geom::IntervalI::getEnd ( ) const

inlinenoexcept

Definition at line 239 of file Interval.h.

{ return _min + _size; }

getMax()

Element lsst::geom::IntervalI::getMax ( ) const

inlinenoexcept

Definition at line 228 of file Interval.h.

{ return _min + _size - 1; }

getMin()

Element lsst::geom::IntervalI::getMin ( ) const

inlinenoexcept

Definition at line 227 of file Interval.h.

{ return _min; }

getSize()

Element lsst::geom::IntervalI::getSize ( ) const

inlinenoexcept

Return slice to extract the interval's region from an ndarray::Array.

For example:

auto array = ndarray::copy(ndarray::arange(5);
auto interval = IntervalI::fromMinMax(2, 4);
auto subarray = array[interval.getSlice()];

Definition at line 247 of file Interval.h.

{ return _size; }

getSlice()

ndarray::View< boost::fusion::vector1< ndarray::index::Range > > lsst::geom::IntervalI::getSlice

(

)

const

Return slice to extract the interval's region from an ndarray::Array.

For example:

auto array = ndarray::copy(ndarray::arange(5);
auto interval = IntervalI::fromMinMax(2, 4);
auto subarray = array[interval.getSlice()];

Definition at line 112 of file Interval.cc.

                                                                             {
    return ndarray::view(getBegin(), getEnd());
}

hash_value()

std::size_t lsst::geom::IntervalI::hash_value ( ) const

noexcept

Return a hash of this object.

Definition at line 199 of file Interval.cc.

                                               {
    // Completely arbitrary seed
    return cpputils::hashCombine(17, _min, _size);
}

intersects()

bool lsst::geom::IntervalI::intersects ( IntervalI const & other ) const

inlinenoexcept

Return slice to extract the interval's region from an ndarray::Array.

For example:

auto array = ndarray::copy(ndarray::arange(5);
auto interval = IntervalI::fromMinMax(2, 4);
auto subarray = array[interval.getSlice()];

Definition at line 283 of file Interval.h.

{ return overlaps(other); }

isDisjointFrom()

bool lsst::geom::IntervalI::isDisjointFrom ( IntervalI const & other ) const

noexcept

Return true if there are no points in both this and other.

Definition at line 130 of file Interval.cc.

                                                                    {
    if (isEmpty() || other.isEmpty()) {
        return true;
    }
    return getMin() > other.getMax() || getMax() < other.getMin();
}

isEmpty()

bool lsst::geom::IntervalI::isEmpty ( ) const

inlinenoexcept

Return true if the interval contains no points.

Definition at line 262 of file Interval.h.

{ return _size == 0; }

operator!=()

bool lsst::geom::IntervalI::operator!= ( IntervalI const & other ) const

noexcept

Compare two intervals for equality.

All empty intervals are equal.

Definition at line 197 of file Interval.cc.

{ return !(other == *this); }

operator=() [1/2]

IntervalI & lsst::geom::IntervalI::operator= ( IntervalI && )

defaultnoexcept

Standard move assignment operatior.

operator=() [2/2]

IntervalI & lsst::geom::IntervalI::operator= ( IntervalI const & )

defaultnoexcept

Standard copy assignment operator.

operator==()

bool lsst::geom::IntervalI::operator== ( IntervalI const & other ) const

noexcept

Compare two intervals for equality.

All empty intervals are equal.

Definition at line 193 of file Interval.cc.

                                                                {
    return other._min == this->_min && other._size == this->_size;
}

overlaps()

bool lsst::geom::IntervalI::overlaps ( IntervalI const & other ) const

noexcept

Return true if there are any points in both this and other.

Any overlap operation involving an empty interval returns false.

Definition at line 128 of file Interval.cc.

{ return !isDisjointFrom(other); }

reflectedAbout()

IntervalI lsst::geom::IntervalI::reflectedAbout

(

Element

point

)

const

Reflect an interval about a point (returning a new object).

Empty intervals remain empty when reflected.

Definition at line 157 of file Interval.cc.

                                                       {
    if (isEmpty()) {
        return IntervalI();
    }
    BigElement max = 2 * static_cast<BigElement>(point) - getMin();
    BigElement min = 2 * static_cast<BigElement>(point) - getMax();
    return _fromMinMaxChecked(min, max);
}

shiftedBy()

IntervalI lsst::geom::IntervalI::shiftedBy

(

Element

offset

)

const

Shift the position of the interval by the given offset (returning a new object).)

Empty intervals remain empty when shifted.

Definition at line 146 of file Interval.cc.

                                                   {
    if (isEmpty()) {
        return IntervalI();
    }
    BigElement min = static_cast<BigElement>(getMin()) + offset;
    BigElement max = static_cast<BigElement>(getMax()) + offset;
    checkForOverflow(min, "minimum");
    checkForOverflow(max, "maximum");
    return IntervalI(static_cast<Element>(min), getSize());
}

swap()

void lsst::geom::IntervalI::swap ( IntervalI & other )

inlinenoexcept

Definition at line 209 of file Interval.h.

                                         {
        using std::swap;
        swap(_size, other._size);
        swap(_min, other._min);
    }

toString()

std::string lsst::geom::IntervalI::toString

(

)

const

Return slice to extract the interval's region from an ndarray::Array.

For example:

auto array = ndarray::copy(ndarray::arange(5);
auto interval = IntervalI::fromMinMax(2, 4);
auto subarray = array[interval.getSlice()];

Definition at line 204 of file Interval.cc.

                                    {
    return (boost::format("(min=%s, max=%s)") % getMin() % getMax()).str();
}

---

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

• /j/snowflake/release/lsstsw/stack/lsst-scipipe-9.0.0/Linux64/geom/g414038480c+5927e1bc1e/include/lsst/geom/Interval.h
• /j/snowflake/release/lsstsw/stack/lsst-scipipe-9.0.0/Linux64/geom/g414038480c+5927e1bc1e/src/Interval.cc