Box#

class lsst.images.Box(y: Interval, x: Interval)#

Bases: object

An axis-aligned 2-d rectangular region.

Parameters#

y

Interval for the y dimension.

x

Interval for the x dimension.

Notes#

Box implements the necessary hooks to be included directly in a pydantic.BaseModel, even though it is neither a built-in type nor a Pydantic model itself.

Attributes Summary

absolute

A factory for constructing a contained Box using slice syntax and absolute coordinates.

bbox

The box itself (Box).

factory

A factory for creating boxes using slice syntax.

local

A factory for constructing a contained Interval using a slice relative to the start of this one (BoxSliceFactory).

max

The inclusive maximum bounds of the box, ordered (y, x) (YX [int]).

min

The inclusive minimum bounds of the box, ordered (y, x) (YX [int]).

shape

Tuple holding the sizes of the intervals, ordered (y, x) (YX [int]).

start

Tuple holding the inclusive Interval.start bvound, ordered (y, x) (YX [int]).

stop

Tuple holding the exclusive Interval.stop bound, ordered (y, x) (YX [int]).

x

The x-dimension interval (int).

y

The y-dimension interval (int).

Methods Summary

boundary()

Iterate over the corners of the box as (y, x) tuples.

contains()

Test whether this box fully contains another or one or more points.

deserialize()

Deserialize a bounds object on the assumption it is a Box.

dilated_by(padding)

Return a new box padded by the given amount on all sides.

from_float_bounds(*, x_min, x_max, y_min, y_max)

Construct a box from floating-point bounds ensuring that all the are contained in the new box.

from_legacy(legacy)

Convert from an lsst.geom.Box2I instance.

from_shape(shape[, start])

Construct a box from its shape and optional start.

intersection()

Return a bounds object that is contained by both self and other.

meshgrid([n, step])

Return a pair of 2-d arrays of the coordinate values of the box.

padded(padding)

Return a new box expanded by the given padding on all sides.

serialize()

Return a Pydantic-friendly representation of this object.

slice_within(other)

Return a tuple of slice objects that correspond to the positions in this box when the items of the container being sliced correspond to other.

to_legacy()

Convert to an lsst.geom.BoxI instance.

Attributes Documentation

absolute#

A factory for constructing a contained Box using slice syntax and absolute coordinates.

Notes#

Slice bounds that are absent are replaced with the bounds of self.

bbox#

The box itself (Box).

This is provided for compatibility with the Bounds interface.

factory: ClassVar[BoxSliceFactory] = <lsst.images._geom.BoxSliceFactory object>#

A factory for creating boxes using slice syntax.

For example:

box = Box.factory[2:5, 3:9]
local#

A factory for constructing a contained Interval using a slice relative to the start of this one (BoxSliceFactory).

Notes#

This factory interprets slices as “local” coordinates, in which 0 corresponds to self.start. Negative bounds are relative to self.stop, as is usually the case for Python sequences.

max#

The inclusive maximum bounds of the box, ordered (y, x) (YX [int]).

min#

The inclusive minimum bounds of the box, ordered (y, x) (YX [int]).

shape#

Tuple holding the sizes of the intervals, ordered (y, x) (YX [int]).

start#

Tuple holding the inclusive Interval.start bvound, ordered (y, x) (YX [int]).

This is an alias for min, typically paired with stop for half-exclusive ranges.

stop#

Tuple holding the exclusive Interval.stop bound, ordered (y, x) (YX [int]).

The values in this tuple are one greater than those in max. It is typically paired with start for half-exclusive ranges.

x#

The x-dimension interval (int).

y#

The y-dimension interval (int).

Methods Documentation

boundary() → Iterator[YX[int]]#

Iterate over the corners of the box as (y, x) tuples.

contains(other: Box, /) → bool#
contains(*, y: int, x: int) → bool
contains(*, y: ndarray, x: ndarray) → ndarray

Test whether this box fully contains another or one or more points.

Parameters#

other

Another box to compare to. Not compatible with the y and x arguments.

y

One or more integer Y coordinates to test for containment. If an array, an array of results will be returned.

x

One or more integer X coordinates to test for containment. If an array, an array of results will be returned.

Returns#

bool | numpy.ndarray

If other was passed or x and y are both scalars, a single bool value. If x and y are arrays, a boolean array with their broadcasted shape.

Notes#

In order to yield the desired behavior for floating-point arguments, points are actually tested against an interval that is 0.5 larger on both sides: this makes positions within the outer boundary of pixels (but beyond the centers of those pixels, which have integer positions) appear “on the image”.

deserialize() → Box#

Deserialize a bounds object on the assumption it is a Box.

This method just returns the Box itself, since that already provides Pydantic serialization hooks. It exists for compatibility with the Bounds protocol.

dilated_by(padding: int) → Box#

Return a new box padded by the given amount on all sides.

classmethod from_float_bounds(*, x_min: float, x_max: float, y_min: float, y_max: float) → Box#

Construct a box from floating-point bounds ensuring that all the are contained in the new box.

Parameters#

x_min

Minimum X value.

x_max

Maximum X value.

y_min

Minimum Y value.

y_max

Maximum Y value.

Notes#

Uses the same rounding convention as lsst.images.Region.bbox, so that pixels whose centers lie within the bounds are included.

classmethod from_legacy(legacy: Any) → Box#

Convert from an lsst.geom.Box2I instance.

classmethod from_shape(shape: Sequence[int], start: Sequence[int] | None = None) → Box#

Construct a box from its shape and optional start.

Parameters#

shape

Sequence of sizes, ordered (y, x) (except for XY instances).

start

Sequence of starts, ordered (y, x) (except for XY instances).

intersection(other: Box) → Box#
intersection(other: Bounds) → Bounds

Return a bounds object that is contained by both self and other.

When there is no overlap, NoOverlapError is raised.

meshgrid(n: int | Sequence[int] | None = None, *, step: float | None = None) → XY[ndarray]#

Return a pair of 2-d arrays of the coordinate values of the box.

Parameters#

n

Number of points in each dimension. If a sequence, points are assumed to be ordered (x, y) unless a YX instance is provided.

step

Set n such that the distance between points is equal to or just less than this in each dimension. Mutually exclusive with n.

Returns#

XY [numpy.ndarray]

A pair of arrays, each of which is 2-d with floating-point values.

See Also#

numpy.meshgrid

padded(padding: int) → Box#

Return a new box expanded by the given padding on all sides.

serialize() → Box#

Return a Pydantic-friendly representation of this object.

This method just returns the Box itself, since that already provides Pydantic serialization hooks. It exists for compatibility with the Bounds protocol.

slice_within(other: Box) → YX[slice]#

Return a tuple of slice objects that correspond to the positions in this box when the items of the container being sliced correspond to other.

This assumes other.contains(self).

to_legacy() → Any#

Convert to an lsst.geom.BoxI instance.