Box

class lsst.images.Box(y, x)

Bases: object

An axis-aligned 2-d rectangular region.

Boxes should generally be constructed by a classmethod factory (e.g. from_shape, from_float_bounds, from_sky_circle) or the factory slicing proxy:

box = Box.factory[y_a:y_b, x_a:x_b]

unless the y and x intervals are already available.

Parameters:

• y (Interval) – Interval for the y dimension.

• x (Interval) – Interval for the x dimension.

Raises:

TypeError – Raised if y or x is not an Interval.

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.
area	The number of pixels in the box (int).
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([other, y, x])	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.
from_sky_circle(sky_projection, center, radius)	Calculate a bounding box from a sky projection and a circular sky region.
intersection(other)	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.
to_polygon()	Convert the box to a polygon with floating-point vertices.
transform(transform)	Apply a coordinate transform to the box, returning a polygon.

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.

area

The number of pixels in the box (int).

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()

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

Yields:

corner – Each corner in turn.

Return type:

Iterator[YX[int]]

contains(other=None, /, *, y=None, x=None)

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

Parameters:

• other (Union[Box, XY[Any], YX[Any], None], default: None) – Another box, or an XY or YX coordinate pair, to compare to. Mutually exclusive with x and y.

• y (Any, default: None) – One or more Y coordinates to test for containment, as a scalar or any array-like. Results are broadcast against x. Mutually exclusive with other.

• x (Any, default: None) – One or more X coordinates to test for containment, as a scalar or any array-like. Results are broadcast against y. Mutually exclusive with other.

Returns:

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

Return type:

bool | numpy.ndarray

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()

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.

Return type:

Box

dilated_by(padding)

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

Parameters:

padding (int) – Number of pixels to pad the box by on every side.

Return type:

Box

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

Parameters:

• x_min (float) – Minimum X value.

• x_max (float) – Maximum X value.

• y_min (float) – Minimum Y value.

• y_max (float) – Maximum Y value.

Return type:

Box

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)

Convert from an lsst.geom.Box2I instance.

Parameters:

legacy (Any) – Legacy lsst.geom.Box2I to convert.

Return type:

Box

classmethod from_shape(shape, start=None)

Construct a box from its shape and optional start.

Parameters:

• shape (Sequence[int]) – Sequence of sizes, ordered (y, x) (except for XY instances).

• start (Sequence[int] | None, default: None) – Sequence of starts, ordered (y, x) (except for XY instances).

Return type:

Box

classmethod from_sky_circle(sky_projection, center, radius)

Calculate a bounding box from a sky projection and a circular sky region.

Parameters:

• sky_projection (SkyProjection) – The sky projection mapping pixels to sky.

• center (SkyCoord) – The center of the circle, as a scalar astropy.coordinates.SkyCoord in any frame.

• radius (Angle) – Radius of the circle, as a scalar astropy.coordinates.Angle.

Returns:

Bounding box enclosing the circle based on the sky projection.

Return type:

Box

Raises:

ValueError – Raised if center or radius is not scalar, or if this image has no sky projection.

intersection(other)

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

When there is no overlap, NoOverlapError is raised.

Parameters:

other (Bounds) – Bounds to intersect with this one.

Return type:

Bounds

meshgrid(n=None, *, step=None)

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

Parameters:

• n (int | Sequence[int] | None, default: None) – Number of points in each dimension. If a sequence, points are assumed to be ordered (x, y) unless a YX instance is provided.

• step (float | None, default: None) – Set n such that the distance between points is equal to or just less than this in each dimension. Mutually exclusive with n.

Returns:

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

Return type:

XY [numpy.ndarray]

See also

numpy.meshgrid

padded(padding)

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

Parameters:

padding (int) – Number of pixels to expand the box by on every side.

Return type:

Box

serialize()

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.

Return type:

Box

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.

This assumes other.contains(self).

Parameters:

other (Box) – Box that the sliced container’s items correspond to.

Return type:

YX[slice]

to_legacy()

Convert to an lsst.geom.BoxI instance.

Return type:

Any

to_polygon()

Convert the box to a polygon with floating-point vertices.

Return type:

Polygon

Notes

Because the integer min and max coordinates of a box are interpreted as pixel centers, these are expanded by 0.5 on all sides before using them to form the polygon vertices.

transform(transform)

Apply a coordinate transform to the box, returning a polygon.

Parameters:

transform (Transform[Any, Any]) – Coordinate transform to apply (in the forward direction).

Return type:

Polygon

Notes

This transforms the polygon representation of the box (see to_polygon), which expands its vertices by 0.5 on all sides to cover full pixels before transforming them.