# BoundingBox¶

class regions.BoundingBox(ixmin, ixmax, iymin, iymax)[source]

Bases: `object`

A rectangular bounding box in integer (not float) pixel indices.

Parameters
ixmin, ixmax, iymin, iymaxint

The bounding box pixel indices. Note that the upper values (`iymax` and `ixmax`) are exclusive as for normal slices in Python. The lower values (`ixmin` and `iymin`) must not be greater than the respective upper values (`ixmax` and `iymax`).

Examples

```>>> from regions import BoundingBox
```
```>>> # constructing a BoundingBox like this is cryptic:
>>> bbox = BoundingBox(1, 10, 2, 20)
```
```>>> # it's better to use keyword arguments for readability:
>>> bbox = BoundingBox(ixmin=1, ixmax=10, iymin=2, iymax=20)
>>> bbox  # nice repr, useful for interactive work
BoundingBox(ixmin=1, ixmax=10, iymin=2, iymax=20)
```
```>>> # sometimes it's useful to check if two bounding boxes are the same
>>> bbox == BoundingBox(ixmin=1, ixmax=10, iymin=2, iymax=20)
True
>>> bbox == BoundingBox(ixmin=7, ixmax=10, iymin=2, iymax=20)
False
```
```>>> # "center" and "shape" can be useful when working with numpy arrays
>>> bbox.center  # numpy order: (y, x)
(10.5, 5.0)
>>> bbox.shape  # numpy order: (y, x)
(18, 9)
```
```>>> # "extent" is useful when plotting the BoundingBox with matplotlib
>>> bbox.extent  # matplotlib order: (x, y)
(0.5, 9.5, 1.5, 19.5)
```

Attributes Summary

 `center` The `(y, x)` center of the bounding box. `extent` The extent of the mask, defined as the `(xmin, xmax, ymin, ymax)` bounding box from the bottom-left corner of the lower-left pixel to the upper-right corner of the upper-right pixel. `shape` The `(ny, nx)` shape of the bounding box.

Methods Summary

 `as_artist`(**kwargs) Return a `matplotlib.patches.Rectangle` that represents the bounding box. `from_float`(xmin, xmax, ymin, ymax) Return the smallest bounding box that fully contains a given rectangle defined by float coordinate values. `get_overlap_slices`(shape) Get slices for the overlapping part of the bounding box and an 2D array. `intersection`(other) Return a `BoundingBox` representing the intersection of this `BoundingBox` with another `BoundingBox`. `plot`([origin, ax]) Plot the `BoundingBox` on a matplotlib `Axes` instance. Return a `RectanglePixelRegion` that represents the bounding box. `union`(other) Return a `BoundingBox` representing the union of this `BoundingBox` with another `BoundingBox`.

Attributes Documentation

center

The `(y, x)` center of the bounding box.

extent

The extent of the mask, defined as the ```(xmin, xmax, ymin, ymax)``` bounding box from the bottom-left corner of the lower-left pixel to the upper-right corner of the upper-right pixel.

The upper edges here are the actual pixel positions of the edges, i.e., they are not “exclusive” indices used for python indexing. This is useful for plotting the bounding box using Matplotlib.

shape

The `(ny, nx)` shape of the bounding box.

Methods Documentation

as_artist(**kwargs)[source]

Return a `matplotlib.patches.Rectangle` that represents the bounding box.

Parameters
**kwargsdict

Any keyword arguments accepted by `matplotlib.patches.Patch`.

Returns
result`matplotlib.patches.Rectangle`

A matplotlib rectangular patch.

Examples

```import numpy as np
import matplotlib.pyplot as plt
from regions import BoundingBox
bbox = BoundingBox(2, 7, 3, 8)
fig = plt.figure()
rng = np.random.default_rng(0)
ax.imshow(rng.random((10, 10)), interpolation='nearest',
cmap='viridis')
lw=2.))
```
classmethod from_float(xmin, xmax, ymin, ymax)[source]

Return the smallest bounding box that fully contains a given rectangle defined by float coordinate values.

Following the pixel index convention, an integer index corresponds to the center of a pixel and the pixel edges span from (index - 0.5) to (index + 0.5). For example, the pixel edge spans of the following pixels are:

• pixel 0: from -0.5 to 0.5

• pixel 1: from 0.5 to 1.5

• pixel 2: from 1.5 to 2.5

In addition, because `BoundingBox` upper limits are exclusive (by definition), 1 is added to the upper pixel edges. See examples below.

Parameters
xmin, xmax, ymin, ymaxfloat

Float coordinates defining a rectangle. The lower values (`xmin` and `ymin`) must not be greater than the respective upper values (`xmax` and `ymax`).

Returns
bbox`BoundingBox` object

The minimal `BoundingBox` object fully containing the input rectangle coordinates.

Examples

```>>> from regions import BoundingBox
>>> BoundingBox.from_float(xmin=1.0, xmax=10.0, ymin=2.0, ymax=20.0)
BoundingBox(ixmin=1, ixmax=11, iymin=2, iymax=21)
```
```>>> BoundingBox.from_float(xmin=1.4, xmax=10.4, ymin=1.6, ymax=10.6)
BoundingBox(ixmin=1, ixmax=11, iymin=2, iymax=12)
```
get_overlap_slices(shape)[source]

Get slices for the overlapping part of the bounding box and an 2D array.

Parameters
shape2-tuple of int

The shape of the 2D array.

Returns
slices_largetuple of slices or `None`

A tuple of slice objects for each axis of the large array, such that `large_array[slices_large]` extracts the region of the large array that overlaps with the small array. `None` is returned if there is no overlap of the bounding box with the given image shape.

slices_smalltuple of slices or `None`

A tuple of slice objects for each axis of an array enclosed by the bounding box such that `small_array[slices_small]` extracts the region that is inside the large array. `None` is returned if there is no overlap of the bounding box with the given image shape.

intersection(other)[source]

Return a `BoundingBox` representing the intersection of this `BoundingBox` with another `BoundingBox`.

Parameters
other`BoundingBox`

The `BoundingBox` to intersect with this one.

Returns
result`BoundingBox`

A `BoundingBox` representing the intersection of the input `BoundingBox` with this one.

plot(origin=(0, 0), ax=None, **kwargs)[source]

Plot the `BoundingBox` on a matplotlib `Axes` instance.

Parameters
originarray_like, optional

The `(x, y)` position of the origin of the displayed image.

ax`matplotlib.axes.Axes`, optional

If `None`, then the current `Axes` instance is used.

**kwargsdict

Any keyword arguments accepted by `matplotlib.patches.Patch`.

Returns
ax`Axes`

Axes on which the patch is added.

to_region()[source]

Return a `RectanglePixelRegion` that represents the bounding box.

union(other)[source]

Return a `BoundingBox` representing the union of this `BoundingBox` with another `BoundingBox`.

Parameters
other`BoundingBox`

The `BoundingBox` to join with this one.

Returns
result`BoundingBox`

A `BoundingBox` representing the union of the input `BoundingBox` with this one.