Box#

Bases: object

A multi-purpose box (ie. rectangle) representation.

Attributes

`area`	Return area of Box.
`extent`	Return a Box(0, 0, h, w) representing the size of this Box.
`height`	Height of the Box.
`size`	(height, width) tuple.
`width`	Width of the Box.

__init__(ymin: int, xmin: int, ymax: int, xmax: int)[source]#

Constructor.

Although primarily intended for representing integer pixel coordinates in a scene, this class can also be used to represent floating point map coordinates though not all methods might be compatible with that interpretation.

Parameters

ymin (int) – minimum y value (y is row)
xmin (int) – minimum x value (x is column)
ymax (int) – maximum y value
xmax (int) – maximum x value

Methods

`__init__`(ymin, xmin, ymax, xmax)	Constructor.
`buffer`(buffer_sz, max_extent)	Return new Box whose sides are buffered by buffer_sz.
`center_crop`(edge_offset_y, edge_offset_x)	Return Box whose sides are eroded by the given offsets.
`copy`()
`erode`(erosion_sz)	Return new Box whose sides are eroded by erosion_sz.
`filter_by_aoi`(windows, aoi_polygons[, within])	Filters windows by a list of AOI polygons
`from_dict`(d)
`from_npbox`(npbox)	Return new Box based on npbox format.
`from_rasterio`(rio_window)	Instantiate from a rasterio window.
`from_shapely`(shape)	Instantiate from the bounds of a shapely geometry.
`geojson_coordinates`()	Return Box as GeoJSON coordinates.
`get_windows`(size, stride[, padding, ...])	Return sliding windows for given size, stride, and padding.
`intersection`(other)	Return the intersection of this Box and the other.
`intersects`(other)
`intersects_aoi`(window, aoi_polygons)	Check if window intersects with the union of given AOI polygons.
`make_random_box_container`(out_h, out_w)	Return a new rectangular Box that contains this Box.
`make_random_square`(size)	Return new randomly positioned square Box that lies inside this Box.
`make_random_square_container`(size)	Return a new square Box that contains this Box.
`make_square`(ymin, xmin, size)	Return new square Box.
`normalize`()	Ensure ymin <= ymax and xmin <= xmax.
`npbox_format`()	Return Box in npbox format used by TF Object Detection API.
`pad`(ymin, xmin, ymax, xmax)	Pad sides by the given amount.
`pad_directional`(padding[, pad_direction])	Pad sides based on given padding and direction.
`rasterio_format`()	Return Box in Rasterio format: ((ymin, ymax), (xmin, xmax)).
`reproject`(transform_fn)	Reprojects this box based on a transform function.
`shapely_format`()
`to_dict`()	Convert to a dict with keys: ymin, xmin, ymax, xmax.
`to_global_coords`(bbox)	Go from bbox coords to global coords.
`to_int`()	Return a new Box with all coordinates cast to ints.
`to_local_coords`(bbox)	Go from to global coords bbox coords.
`to_npboxes`(boxes)	Return nx4 numpy array from list of Box.
`to_points`()	Get (x, y) coords of each vertex as a 4x2 numpy array.
`to_rasterio`()	Convert to a Rasterio Window.
`to_shapely`()	Convert to shapely Polygon.
`to_slices`([h_step, w_step])	Convert to slices: ymin:ymax[:h_step], xmin:xmax[:w_step]
`to_xywh`()	Convert to (xmin, ymin, width, height) tuple
`to_xyxy`()	Convert to (xmin, ymin, xmax, ymax) tuple
`translate`(dy, dx)	Translate window along y and x axes by the given distances.
`tuple_format`()	Return a (ymin, xmin, ymax, xmax) tuple.
`within_aoi`(window, aoi_polygons)	Check if window is within the union of given AOI polygons.

__contains__(query: Self | tuple[int, int]) → bool[source]#

Check if box or point is contained within this box.

Parameters: query (Self | tuple[int, int]) – Box or single point (x, y).
Raises: NotImplementedError – if query is not a Box or tuple/list.
Return type: bool

__getitem__(i: int)[source]#

Parameters: i (int) –

__init__(ymin: int, xmin: int, ymax: int, xmax: int)[source]#

Constructor.

Parameters

ymin (int) – minimum y value (y is row)
xmin (int) – minimum x value (x is column)
ymax (int) – maximum y value
xmax (int) – maximum x value

buffer(buffer_sz: float, max_extent: Self) → Self[source]#

Return new Box whose sides are buffered by buffer_sz.

The resulting box is clipped so that the values of the corners are always greater than zero and less than the height and width of max_extent.

Parameters

buffer_sz (float) –
max_extent (Self) –

Return type

Self

center_crop(edge_offset_y: int, edge_offset_x: int) → Self[source]#

Return Box whose sides are eroded by the given offsets.

Box(0, 0, 10, 10).center_crop(2, 4) == Box(2, 4, 8, 6)

Parameters

edge_offset_y (int) –
edge_offset_x (int) –

Return type

Self

copy() → Self[source]#

Return type: Self

erode(erosion_sz) → Self[source]#

Return new Box whose sides are eroded by erosion_sz.

Return type: Self

static filter_by_aoi(windows: Sequence[Box], aoi_polygons: list[shapely.geometry.polygon.Polygon], within: bool = True) → tuple[list[rastervision.core.box.Box], list[int]][source]#

Filters windows by a list of AOI polygons

Parameters

within (bool) – if True, windows are only kept if they lie fully within an AOI polygon. Otherwise, windows are kept if they intersect an AOI polygon.
windows (Sequence[Box]) –
aoi_polygons (list[shapely.geometry.polygon.Polygon]) –

Return type

tuple[list[rastervision.core.box.Box], list[int]]

classmethod from_dict(d: dict) → Self[source]#

Parameters: d (dict) –
Return type: Self

classmethod from_npbox(npbox: ndarray) → Self[source]#

Return new Box based on npbox format.

Parameters: npbox (ndarray) – Numpy array of form [ymin, xmin, ymax, xmax] with float type
Return type: Self

classmethod from_rasterio(rio_window: Window) → Self[source]#

Instantiate from a rasterio window.

Parameters: rio_window (Window) –
Return type: Self

classmethod from_shapely(shape: BaseGeometry) → Self[source]#

Instantiate from the bounds of a shapely geometry.

Parameters: shape (BaseGeometry) –
Return type: Self

geojson_coordinates() → list[tuple[int, int]][source]#

Return Box as GeoJSON coordinates.

Return type: list[tuple[int, int]]

get_windows(size: Union[int, tuple[int, int]], stride: Union[int, tuple[int, int]], padding: Optional[Union[int, tuple[int, int]]] = None, pad_direction: Literal['both', 'start', 'end'] = 'end') → SlidingWindows[source]#

Return sliding windows for given size, stride, and padding.

Each of size, stride, and padding can be either a positive int or a tuple (vertical-component, horizontal-component) of positive ints.

If padding is not specified and stride <= size, it will be automatically calculated such that the windows cover the entire extent.

Parameters

box – Outer box within which to generate sliding windows.
size (Union[int, tuple[int, int]]) – Size (h, w) of the windows.
stride (Union[int, tuple[int, int]]) – Step size between windows. Can be a (h_step, w_step) tuple or positive int.
padding (Optional[Union[int, tuple[int, int]]]) – Optional padding to accommodate windows that overflow the extent. Can be a (h_pad, w_pad) tuple or a non-negative int. If None, will be automatically calculated such that the windows cover the entire extent. Defaults to None.
pad_direction (Literal['both', 'start', 'end']) – Directions to add padding to. If 'end', only add padding to bottom and right. If 'start', only add padding to top and left. If 'both', add padding to all sides. Has no effect if padding is zero. Defaults to 'end'.

Returns

Lazy list of windows.

Return type

SlidingWindows

intersection(other: Self) → Self[source]#

Return the intersection of this Box and the other.

Parameters: other (Self) – The box to intersect with this one.
Returns: The intersection of this box and the other one.
Return type: Self

intersects(other: Self) → bool[source]#

Parameters: other (Self) –
Return type: bool

static intersects_aoi(window: Box, aoi_polygons: shapely.geometry.polygon.Polygon | list[shapely.geometry.polygon.Polygon]) → bool[source]#

Check if window intersects with the union of given AOI polygons.

Parameters

window (Box) –
aoi_polygons (shapely.geometry.polygon.Polygon | list[shapely.geometry.polygon.Polygon]) –

Return type

bool

make_random_box_container(out_h: int, out_w: int) → Self[source]#

Return a new rectangular Box that contains this Box.

Parameters

out_h (int) – the height of the new Box
out_w (int) – the width of the new Box

Return type

Self

make_random_square(size: int) → Self[source]#

Return new randomly positioned square Box that lies inside this Box.

Parameters: size (int) – the height and width of the new Box
Return type: Self

make_random_square_container(size: int) → Self[source]#

Return a new square Box that contains this Box.

Parameters: size (int) – the width and height of the new Box
Return type: Self

static make_square(ymin, xmin, size) → Self[source]#

Return new square Box.

Return type: Self

normalize() → Self[source]#

Ensure ymin <= ymax and xmin <= xmax.

Return type: Self

npbox_format() → ndarray[source]#

Return Box in npbox format used by TF Object Detection API.

Returns: Numpy array of form [ymin, xmin, ymax, xmax] with float type
Return type: ndarray

pad(ymin: int, xmin: int, ymax: int, xmax: int) → Self[source]#

Pad sides by the given amount.

Parameters

ymin (int) –
xmin (int) –
ymax (int) –
xmax (int) –

Return type

Self

pad_directional(padding: Annotated[int, Ge(ge=0)]], int], pad_direction: Literal['both', 'start', 'end'] = 'end') → Self[source]#

Pad sides based on given padding and direction.

Parameters

padding (Union[tuple[Annotated[int, Ge(ge=0)], Annotated[int, Ge(ge=0)]], int]) –
pad_direction (Literal['both', 'start', 'end']) –

Return type

Self

rasterio_format() → tuple[tuple[int, int], tuple[int, int]][source]#

Return Box in Rasterio format: ((ymin, ymax), (xmin, xmax)).

Return type: tuple[tuple[int, int], tuple[int, int]]

reproject(transform_fn: Callable[[tuple], tuple]) → Self[source]#

Reprojects this box based on a transform function.

Parameters: transform_fn (Callable[[tuple], tuple]) – A function that takes in a tuple (x, y) and reprojects that point to the target coordinate reference system.
Return type: Self

shapely_format() → tuple[int, int, int, int][source]#

Return type: tuple[int, int, int, int]

to_dict() → dict[str, int][source]#

Convert to a dict with keys: ymin, xmin, ymax, xmax.

Return type: dict[str, int]

to_global_coords(bbox: Self) → Self[source]#

Go from bbox coords to global coords.

E.g., Given a box Box(20, 20, 40, 40) and bbox Box(20, 20, 100, 100), the box becomes Box(40, 40, 60, 60).

Inverse of Box.to_local_coords().

Parameters: bbox (Self) –
Return type: Self

to_int()[source]#: Return a new Box with all coordinates cast to ints.

to_local_coords(bbox: Self) → Self[source]#

Go from to global coords bbox coords.

E.g., Given a box Box(40, 40, 60, 60) and bbox Box(20, 20, 100, 100), the box becomes Box(20, 20, 40, 40).

Inverse of Box.to_global_coords().

Parameters: bbox (Self) –
Return type: Self

static to_npboxes(boxes: list['Self']) → ndarray[source]#

Return nx4 numpy array from list of Box.

Parameters: boxes (list['Self']) –
Return type: ndarray

to_points() → ndarray[source]#

Get (x, y) coords of each vertex as a 4x2 numpy array.

Return type: ndarray

to_rasterio() → Window[source]#

Convert to a Rasterio Window.

Return type: Window

to_shapely() → Polygon[source]#

Convert to shapely Polygon.

Return type: Polygon

to_slices(h_step: int | None = None, w_step: int | None = None) → tuple[slice, slice][source]#

Convert to slices: ymin:ymax[:h_step], xmin:xmax[:w_step]

Parameters

h_step (int | None) –
w_step (int | None) –

Return type

tuple[slice, slice]

to_xywh() → tuple[int, int, int, int][source]#

Convert to (xmin, ymin, width, height) tuple

Return type: tuple[int, int, int, int]

to_xyxy() → tuple[int, int, int, int][source]#

Convert to (xmin, ymin, xmax, ymax) tuple

Return type: tuple[int, int, int, int]

translate(dy: int, dx: int) → Self[source]#

Translate window along y and x axes by the given distances.

Parameters

dy (int) –
dx (int) –

Return type

Self

tuple_format() → tuple[int, int, int, int][source]#

Return a (ymin, xmin, ymax, xmax) tuple.

Return type: tuple[int, int, int, int]

static within_aoi(window: Box, aoi_polygons: shapely.geometry.polygon.Polygon | list[shapely.geometry.polygon.Polygon]) → bool[source]#

Check if window is within the union of given AOI polygons.

Parameters

window (Box) –
aoi_polygons (shapely.geometry.polygon.Polygon | list[shapely.geometry.polygon.Polygon]) –

Return type

bool

property area: int#: Return area of Box.

property extent: Self#: Return a Box(0, 0, h, w) representing the size of this Box.

property height: int#: Height of the Box.

property size: tuple[int, int]#: (height, width) tuple.

property width: int#: Width of the Box.