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).
shape	Tuple holding the sizes of the intervals ordered (y, x) (YX [int]).
start	Tuple holding the starts of the intervals 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(serialized)	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_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.

shape

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

start

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

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

classmethod deserialize(serialized: SerializableBounds) → 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_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.