Public Member Functions
	__init__ (self, tuple[int,...] shape, tuple[int,...]\|None origin=None)

bool	contains (self, Sequence[int] p)

int	ndim (self)

tuple[int,...]	start (self)

tuple[int,...]	stop (self)

tuple[float,...]	center (self)

tuple[tuple[int, int],...]	bounds (self)

tuple[slice,...]	slices (self)

Box	grow (self, int\|tuple[int,...] radius)

Box	shifted_by (self, Sequence[int] shift)

bool	intersects (self, Box other)

tuple[tuple[slice,...], tuple[slice,...]]	overlapped_slices (self, Box other)

Box	__or__ (self, Box other)

Box	__and__ (self, Box other)

Box	__getitem__ (self, int\|slice\|tuple[int,...] index)

str	__repr__ (self)

Box	__add__ (self, int\|Sequence[int] offset)

Box	__sub__ (self, int\|Sequence[int] offset)

Box	__matmul__ (self, Box bbox)

Box	__copy__ (self)

Box	copy (self)

bool	__eq__ (self, object other)

int	__hash__ (self)

Static Public Member Functions
Box	from_bounds (*tuple[int,...] bounds)

Box	from_data (np.ndarray x, float threshold=0)

Public Attributes
	shape

	origin

	ndim

Protected Member Functions
tuple[int,...]	_offset_to_tuple (self, int\|Sequence[int] offset)

Detailed Description

Bounding Box for an object

A Bounding box describes the location of a data unit in the
global/model coordinate system, using the row-major
(default numpy/C++) ordering convention.
So, for example, a 2D image will have shape ``(height, width)``,
however the bounding `Box` code is agnostic as to number of dimensions
or the meaning of those dimensions.

Examples
--------

At a minimum a new `Box` can be initialized using the ``shape`` of the
region it describes:

>>> from lsst.scarlet.lite import Box
>>> bbox = Box((3, 4, 5, 6))
>>> print(bbox)
Box(shape=(3, 4, 5, 6), origin=(0, 0, 0, 0))

If the region described by the `Box` is offset from the zero origin,
a new ``origin`` can be passed to the constructor

>>> bbox = Box((3, 4, 5, 6), (2, 4, 7, 9))
>>> print(bbox)
Box(shape=(3, 4, 5, 6), origin=(2, 4, 7, 9))

It is also possible to initialize a `Box` from a collection of tuples,
where tuple is a pair of integers representing the
first and last index in each dimension. For example:

>>> bbox = Box.from_bounds((3, 6), (11, 21))
>>> print(bbox)
Box(shape=(3, 10), origin=(3, 11))

It is also possible to initialize a `Box` by thresholding a numpy array
and including only the region of the image above the threshold in the
resulting `Box`. For example

>>> from lsst.scarlet.lite.utils import integrated_circular_gaussian
>>> data = integrated_circular_gaussian(sigma=1.0)
>>> bbox = Box.from_data(data, 1e-2)
>>> print(bbox)
Box(shape=(5, 5), origin=(5, 5))

The `Box` class contains a number of convenience methods that can be used
to extract subsets of an array, combine bounding boxes, etc.

For example, using the ``data`` and ``bbox`` from the end of the previous
section, the portion of the data array that is contained in the bounding
box can be extraced usng the `Box.slices` method:

>>> subset = data[bbox.slices]

The intersection of two boxes can be calcualted using the ``&`` operator,
for example

>>> bbox = Box((5, 5)) & Box((5, 5), (2, 2))
>>> print(bbox)
Box(shape=(3, 3), origin=(2, 2))

Similarly, the union of two boxes can be calculated using the ``|``
operator:

>>> bbox = Box((5, 5)) | Box((5, 5), (2, 2))
>>> print(bbox)
Box(shape=(7, 7), origin=(0, 0))

To find out of a point is located in a `Box` use

>>> contains = bbox.contains((3, 3))
>>> print(contains)
True

To find out if two boxes intersect (in other words ``box1 & box2`` has a
non-zero size) use

>>> intersects = bbox.intersects(Box((10, 10), (100, 100)))
>>> print(intersects)
False

It is also possible to shift a box by a vector (sequence):

>>> bbox = bbox + (50, 60)
>>> print(bbox)
Box(shape=(7, 7), origin=(50, 60))

which can also be negative

>>> bbox = bbox - (5, -5)
>>> print(bbox)
Box(shape=(7, 7), origin=(45, 65))

Boxes can also be converted into higher dimensions using the
``@`` operator:

>>> bbox1 = Box((10,), (3, ))
>>> bbox2 = Box((101, 201), (18, 21))
>>> bbox = bbox1 @ bbox2
>>> print(bbox)
Box(shape=(10, 101, 201), origin=(3, 18, 21))

Boxes are equal when they have the same shape and the same origin, so

>>> print(Box((10, 10), (5, 5)) == Box((10, 10), (5, 5)))
True

>>> print(Box((10, 10), (5, 5)) == Box((10, 10), (4, 4)))
False

Finally, it is common to insert one array into another when their bounding
boxes only partially overlap.
In order to correctly insert the overlapping portion of the array it is
convenient to calculate the slices from each array that overlap.
For example:

>>> import numpy as np
>>> x = np.arange(12).reshape(3, 4)
>>> y = np.arange(9).reshape(3, 3)
>>> print(x)
[[ 0  1  2  3]
 [ 4  5  6  7]
 [ 8  9 10 11]]
>>> print(y)
[[0 1 2]
 [3 4 5]
 [6 7 8]]
>>> x_box = Box.from_data(x) + (3, 4)
>>> y_box = Box.from_data(y) + (1, 3)
>>> slices = x_box.overlapped_slices(y_box)
>>> x[slices[0]] += y[slices[1]]
>>> print(x)
[[ 7  9  2  3]
 [ 4  5  6  7]
 [ 8  9 10 11]]

Parameters
----------
shape:
    Size of the box in each dimension.
origin:
    Minimum corner coordinate of the box.
    This defaults to ``(0, ...)``.

Definition at line 31 of file bbox.py.

Constructor & Destructor Documentation

◆ init()

lsst.scarlet.lite.bbox.Box.__init__	(		self,
		tuple[int, ...]	shape,
		tuple[int, ...] \| None	origin = None )

Definition at line 177 of file bbox.py.

    def __init__(self, shape: tuple[int, ...], origin: tuple[int, ...] | None = None):
        self.shape = tuple(shape)
        if origin is None:
            origin = (0,) * len(shape)
        if len(origin) != len(shape):
            msg = "Mismatched origin and shape dimensions. "
            msg += f"Received {len(origin)} and {len(shape)}"
            raise ValueError(msg)
        self.origin = tuple(origin)
 

Member Function Documentation

◆ add()

Box lsst.scarlet.lite.bbox.Box.__add__	(		self,
		int \| Sequence[int]	offset )

Generate a new Box with a shifted offset

Parameters
----------
offset:
    The amount to shift the current offset

Returns
-------
result:
    The shifted box.

Definition at line 416 of file bbox.py.

    def __add__(self, offset: int | Sequence[int]) -> Box:
        """Generate a new Box with a shifted offset
 
        Parameters
        ----------
        offset:
            The amount to shift the current offset
 
        Returns
        -------
        result:
            The shifted box.
        """
        return self.shifted_by(self._offset_to_tuple(offset))
 

◆ and()

Box lsst.scarlet.lite.bbox.Box.__and__	(		self,
		Box	other )

Intersection of two bounding boxes

If there is no intersection between the two bounding
boxes then an empty bounding box is returned.

Parameters
----------
other:
    The other bounding box in the intersection

Returns
-------
result:
    The rectangular box that is in the overlap region
    of both boxes.

Definition at line 355 of file bbox.py.

    def __and__(self, other: Box) -> Box:
        """Intersection of two bounding boxes
 
        If there is no intersection between the two bounding
        boxes then an empty bounding box is returned.
 
        Parameters
        ----------
        other:
            The other bounding box in the intersection
 
        Returns
        -------
        result:
            The rectangular box that is in the overlap region
            of both boxes.
        """
        if other.ndim != self.ndim:
            raise ValueError(f"Dimension mismatch in the boxes {other=} and {self=}")
 
        bounds = []
        for d in range(self.ndim):
            bounds.append((max(self.start[d], other.start[d]), min(self.stop[d], other.stop[d])))
        return Box.from_bounds(*bounds)
 

◆ copy()

Box lsst.scarlet.lite.bbox.Box.__copy__ ( self )

Copy of the box

Definition at line 465 of file bbox.py.

    def __copy__(self) -> Box:
        """Copy of the box"""
        return Box(self.shape, origin=self.origin)
 

◆ eq()

bool lsst.scarlet.lite.bbox.Box.__eq__	(		self,
		object	other )

Check for equality.

Two boxes are equal when they have the same shape and origin.

Definition at line 473 of file bbox.py.

    def __eq__(self, other: object) -> bool:
        """Check for equality.
 
        Two boxes are equal when they have the same shape and origin.
        """
        if not hasattr(other, "shape") and not hasattr(other, "origin"):
            return False
        return self.shape == other.shape and self.origin == other.origin  # type: ignore
 

◆ getitem()

Box lsst.scarlet.lite.bbox.Box.__getitem__	(		self,
		int \| slice \| tuple[int, ...]	index )

Definition at line 380 of file bbox.py.

    def __getitem__(self, index: int | slice | tuple[int, ...]) -> Box:
        if isinstance(index, int) or isinstance(index, slice):
            s_ = self.shape[index]
            o_ = self.origin[index]
            if isinstance(s_, int):
                s_ = (s_,)
                o_ = (cast(int, o_),)  # type: ignore
        else:
            iter(index)
            # If I is a Sequence then select the indices in `index`, in order
            s_ = tuple(self.shape[i] for i in index)
            o_ = tuple(self.origin[i] for i in index)
        return Box(s_, origin=cast(tuple[int, ...], o_))
 

◆ hash()

int lsst.scarlet.lite.bbox.Box.__hash__ ( self )

Definition at line 482 of file bbox.py.

    def __hash__(self) -> int:
        return hash((self.shape, self.origin))

◆ matmul()

Box lsst.scarlet.lite.bbox.Box.__matmul__	(		self,
		Box	bbox )

Combine two Boxes into a higher dimensional box

Parameters
----------
bbox:
    The box to append to this box.

Returns
-------
result:
    The combined Box.

Definition at line 448 of file bbox.py.

    def __matmul__(self, bbox: Box) -> Box:
        """Combine two Boxes into a higher dimensional box
 
        Parameters
        ----------
        bbox:
            The box to append to this box.
 
        Returns
        -------
        result:
            The combined Box.
        """
        bounds = self.bounds + bbox.bounds
        result = Box.from_bounds(*bounds)
        return result
 

◆ or()

Box lsst.scarlet.lite.bbox.Box.__or__	(		self,
		Box	other )

Union of two bounding boxes

Parameters
----------
other:
    The other bounding box in the union

Returns
-------
result:
    The smallest rectangular box that contains *both* boxes.

Definition at line 335 of file bbox.py.

    def __or__(self, other: Box) -> Box:
        """Union of two bounding boxes
 
        Parameters
        ----------
        other:
            The other bounding box in the union
 
        Returns
        -------
        result:
            The smallest rectangular box that contains *both* boxes.
        """
        if other.ndim != self.ndim:
            raise ValueError(f"Dimension mismatch in the boxes {other} and {self}")
        bounds = []
        for d in range(self.ndim):
            bounds.append((min(self.start[d], other.start[d]), max(self.stop[d], other.stop[d])))
        return Box.from_bounds(*bounds)
 

◆ repr()

str lsst.scarlet.lite.bbox.Box.__repr__ ( self )

Definition at line 394 of file bbox.py.

    def __repr__(self) -> str:
        return f"Box(shape={self.shape}, origin={self.origin})"
 

◆ sub()

Box lsst.scarlet.lite.bbox.Box.__sub__	(		self,
		int \| Sequence[int]	offset )

Generate a new Box with a shifted offset in the negative direction

Parameters
----------
offset:
    The amount to shift the current offset

Returns
-------
result:
    The shifted box.

Definition at line 431 of file bbox.py.

    def __sub__(self, offset: int | Sequence[int]) -> Box:
        """Generate a new Box with a shifted offset in the negative direction
 
        Parameters
        ----------
        offset:
            The amount to shift the current offset
 
        Returns
        -------
        result:
            The shifted box.
        """
        offset = self._offset_to_tuple(offset)
        offset = tuple(-o for o in offset)
        return self.shifted_by(offset)
 

◆ _offset_to_tuple()

tuple[int, ...] lsst.scarlet.lite.bbox.Box._offset_to_tuple	(		self,
		int \| Sequence[int]	offset )

protected

Expand an integer offset into a tuple

Parameters
----------
offset:
    The offset to (potentially) convert into a tuple.

Returns
-------
offset:
    The offset as a tuple.

Definition at line 397 of file bbox.py.

    def _offset_to_tuple(self, offset: int | Sequence[int]) -> tuple[int, ...]:
        """Expand an integer offset into a tuple
 
        Parameters
        ----------
        offset:
            The offset to (potentially) convert into a tuple.
 
        Returns
        -------
        offset:
            The offset as a tuple.
        """
        if isinstance(offset, int):
            _offset = (offset,) * self.ndim
        else:
            _offset = tuple(offset)
        return _offset
 

◆ bounds()

tuple[tuple[int, int], ...] lsst.scarlet.lite.bbox.Box.bounds ( self )

Bounds of the box

Definition at line 267 of file bbox.py.

    def bounds(self) -> tuple[tuple[int, int], ...]:
        """Bounds of the box"""
        return tuple((o, o + s) for o, s in zip(self.origin, self.shape))
 

◆ center()

tuple[float, ...] lsst.scarlet.lite.bbox.Box.center ( self )

Tuple of center coordinates

Definition at line 262 of file bbox.py.

    def center(self) -> tuple[float, ...]:
        """Tuple of center coordinates"""
        return tuple(o + s / 2 for o, s in zip(self.origin, self.shape))
 

◆ contains()

bool lsst.scarlet.lite.bbox.Box.contains	(		self,
		Sequence[int]	p )

Whether the box contains a given coordinate `p`

Definition at line 236 of file bbox.py.

    def contains(self, p: Sequence[int]) -> bool:
        """Whether the box contains a given coordinate `p`"""
        if len(p) != self.ndim:
            raise ValueError(f"Dimension mismatch in {p} and {self.ndim}")
 
        for d in range(self.ndim):
            if not (p[d] >= self.origin[d] and (p[d] < (self.origin[d] + self.shape[d]))):
                return False
        return True
 

◆ copy()

Box lsst.scarlet.lite.bbox.Box.copy ( self )

Copy of the box

Definition at line 469 of file bbox.py.

    def copy(self) -> Box:
        """Copy of the box"""
        return self.__copy__()
 

◆ from_bounds()

Box lsst.scarlet.lite.bbox.Box.from_bounds ( *tuple[int, ...] bounds )

static

Initialize a box from its bounds

Parameters
----------
bounds:
    Min/Max coordinate for every dimension

Returns
-------
bbox:
    A new box bounded by the input bounds.

Definition at line 188 of file bbox.py.

    def from_bounds(*bounds: tuple[int, ...]) -> Box:
        """Initialize a box from its bounds
 
        Parameters
        ----------
        bounds:
            Min/Max coordinate for every dimension
 
        Returns
        -------
        bbox:
            A new box bounded by the input bounds.
        """
        shape = tuple(max(0, cmax - cmin) for cmin, cmax in bounds)
        origin = tuple(cmin for cmin, cmax in bounds)
        return Box(shape, origin=origin)
 

◆ from_data()

Box lsst.scarlet.lite.bbox.Box.from_data	(	np.ndarray	x,
		float	threshold = 0 )

static

Define range of `x` above `min_value`.

This method creates the smallest `Box` that contains all of the
elements in `x` that are above `min_value`.

Parameters
----------
x:
    Data to threshold to specify the shape/dimensionality of `x`.
threshold:
    Threshold for the data.
    The box is trimmed so that all elements bordering `x` smaller than
    `min_value` are ignored.

Returns
-------
bbox:
    Bounding box for the thresholded `x`

Definition at line 206 of file bbox.py.

    def from_data(x: np.ndarray, threshold: float = 0) -> Box:
        """Define range of `x` above `min_value`.
 
        This method creates the smallest `Box` that contains all of the
        elements in `x` that are above `min_value`.
 
        Parameters
        ----------
        x:
            Data to threshold to specify the shape/dimensionality of `x`.
        threshold:
            Threshold for the data.
            The box is trimmed so that all elements bordering `x` smaller than
            `min_value` are ignored.
 
        Returns
        -------
        bbox:
            Bounding box for the thresholded `x`
        """
        sel = x > threshold
        if sel.any():
            nonzero = np.where(sel)
            bounds = []
            for dim in range(len(x.shape)):
                bounds.append((nonzero[dim].min(), nonzero[dim].max() + 1))
        else:
            bounds = [(0, 0)] * len(x.shape)
        return Box.from_bounds(*bounds)
 

◆ grow()

Box lsst.scarlet.lite.bbox.Box.grow	(		self,
		int \| tuple[int, ...]	radius )

Grow the Box by the given radius in each direction

Definition at line 278 of file bbox.py.

    def grow(self, radius: int | tuple[int, ...]) -> Box:
        """Grow the Box by the given radius in each direction"""
        if isinstance(radius, int):
            radius = tuple([radius] * self.ndim)
        origin = tuple([self.origin[d] - radius[d] for d in range(self.ndim)])
        shape = tuple([self.shape[d] + 2 * radius[d] for d in range(self.ndim)])
        return Box(shape, origin=origin)
 

◆ intersects()

bool lsst.scarlet.lite.bbox.Box.intersects	(		self,
		Box	other )

Check if two boxes overlap

Parameters
----------
other:
    The boxes to check for overlap

Returns
-------
result:
    True when the two boxes overlap.

Definition at line 302 of file bbox.py.

    def intersects(self, other: Box) -> bool:
        """Check if two boxes overlap
 
        Parameters
        ----------
        other:
            The boxes to check for overlap
 
        Returns
        -------
        result:
            True when the two boxes overlap.
        """
        overlap = self & other
        return np.all(np.array(overlap.shape) != 0)  # type: ignore
 

◆ ndim()

int lsst.scarlet.lite.bbox.Box.ndim ( self )

Dimensionality of this BBox

Definition at line 247 of file bbox.py.

    def ndim(self) -> int:
        """Dimensionality of this BBox"""
        return len(self.shape)
 

◆ overlapped_slices()

tuple[tuple[slice, ...], tuple[slice, ...]] lsst.scarlet.lite.bbox.Box.overlapped_slices	(		self,
		Box	other )

Return `slice` for the box that contains the overlap of this and
another `Box`

Parameters
----------
other:

Returns
-------
slices:
    The slice of an array bounded by `self` and
    the slice of an array bounded by `other` in the
    overlapping region.

Definition at line 318 of file bbox.py.

    def overlapped_slices(self, other: Box) -> tuple[tuple[slice, ...], tuple[slice, ...]]:
        """Return `slice` for the box that contains the overlap of this and
        another `Box`
 
        Parameters
        ----------
        other:
 
        Returns
        -------
        slices:
            The slice of an array bounded by `self` and
            the slice of an array bounded by `other` in the
            overlapping region.
        """
        return overlapped_slices(self, other)
 

◆ shifted_by()

Box lsst.scarlet.lite.bbox.Box.shifted_by	(		self,
		Sequence[int]	shift )

Generate a shifted copy of this box

Parameters
----------
shift:
    The amount to shift each axis to create the new box

Returns
-------
result:
    The resulting bounding box.

Definition at line 286 of file bbox.py.

    def shifted_by(self, shift: Sequence[int]) -> Box:
        """Generate a shifted copy of this box
 
        Parameters
        ----------
        shift:
            The amount to shift each axis to create the new box
 
        Returns
        -------
        result:
            The resulting bounding box.
        """
        origin = tuple(o + shift[i] for i, o in enumerate(self.origin))
        return Box(self.shape, origin=origin)
 

◆ slices()

tuple[slice, ...] lsst.scarlet.lite.bbox.Box.slices ( self )

Bounds of the box as slices

Definition at line 272 of file bbox.py.

    def slices(self) -> tuple[slice, ...]:
        """Bounds of the box as slices"""
        if np.any(self.origin) < 0:
            raise ValueError("Cannot get slices for a box with negative indices")
        return tuple([slice(o, o + s) for o, s in zip(self.origin, self.shape)])
 

◆ start()

tuple[int, ...] lsst.scarlet.lite.bbox.Box.start ( self )

Tuple of start coordinates

Definition at line 252 of file bbox.py.

    def start(self) -> tuple[int, ...]:
        """Tuple of start coordinates"""
        return self.origin
 

◆ stop()

tuple[int, ...] lsst.scarlet.lite.bbox.Box.stop ( self )

Tuple of stop coordinates

Definition at line 257 of file bbox.py.

    def stop(self) -> tuple[int, ...]:
        """Tuple of stop coordinates"""
        return tuple(o + s for o, s in zip(self.origin, self.shape))
 

Member Data Documentation

◆ ndim

lsst.scarlet.lite.bbox.Box.ndim

Definition at line 241 of file bbox.py.

◆ origin

lsst.scarlet.lite.bbox.Box.origin

Definition at line 185 of file bbox.py.

◆ shape

lsst.scarlet.lite.bbox.Box.shape

Definition at line 178 of file bbox.py.

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

/j/snowflake/release/lsstsw/stack/lsst-scipipe-8.0.0/Linux64/scarlet_lite/gae0086650b+585e252eca/python/lsst/scarlet/lite/bbox.py

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ __init__()

Member Function Documentation

◆ __add__()

◆ __and__()

◆ __copy__()

◆ __eq__()

◆ __getitem__()

◆ __hash__()

◆ __matmul__()

◆ __or__()

◆ __repr__()

◆ __sub__()

◆ _offset_to_tuple()

◆ bounds()

◆ center()

◆ contains()

◆ copy()

◆ from_bounds()

◆ from_data()

◆ grow()

◆ intersects()

◆ ndim()

◆ overlapped_slices()

◆ shifted_by()

◆ slices()

◆ start()

◆ stop()

Member Data Documentation

◆ ndim

◆ origin

◆ shape

◆ init()

◆ add()

◆ and()

◆ copy()

◆ eq()

◆ getitem()

◆ hash()

◆ matmul()

◆ or()

◆ repr()

◆ sub()