Box#

class Box[source]#

Bases: object

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

Attributes

area

Return area of Box.

extent

Return a (0, 0, h, w) Box representing the size of this Box.

height

Return height of Box.

size

width

Return width of Box.

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

Construct a bounding box.

Unless otherwise stated, the convention is that these coordinates are in pixel coordinates and represent boxes that lie within a RasterSource.

Parameters
  • ymin – minimum y value (y is row)

  • xmin – minimum x value (x is column)

  • ymax – maximum y value

  • xmax – maximum x value

Methods

__init__(ymin, xmin, ymax, xmax)

Construct a bounding box.

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, ...])

Returns a list of boxes representing windows generated using a sliding window traversal with the specified size, stride, and padding.

intersection(other)

Return the intersection of this Box and the other.

intersects(other)

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.

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

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

within_aoi(window, aoi_polygons)

Check if window is within a list of AOI polygons.

__contains__(query: Union[Box, Sequence]) bool[source]#

Check if box or point is contained within this box.

Parameters

query (Union[Box, Sequence]) – Box or single point (x, y).

Raises

NotImplementedError – if query is not a Box or tuple/list.

Return type

bool

__getitem__(i)[source]#
__init__(ymin, xmin, ymax, xmax)[source]#

Construct a bounding box.

Unless otherwise stated, the convention is that these coordinates are in pixel coordinates and represent boxes that lie within a RasterSource.

Parameters
  • ymin – minimum y value (y is row)

  • xmin – minimum x value (x is column)

  • ymax – maximum y value

  • xmax – maximum x value

buffer(buffer_sz: float, max_extent: Box) Box[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 (Box) –

Return type

Box

center_crop(edge_offset_y: int, edge_offset_x: int) Box[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

Box

copy() Box[source]#
Return type

Box

erode(erosion_sz) Box[source]#

Return new Box whose sides are eroded by erosion_sz.

Return type

Box

static filter_by_aoi(windows: List[Box], aoi_polygons: List[Polygon], within: bool = True) List[Box][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 (List[Box]) –

  • aoi_polygons (List[Polygon]) –

Return type

List[Box]

classmethod from_dict(d: dict) Box[source]#
Parameters

d (dict) –

Return type

Box

static from_npbox(npbox)[source]#

Return new Box based on npbox format.

Parameters

npbox – Numpy array of form [ymin, xmin, ymax, xmax] with float type

classmethod from_rasterio(rio_window: Window) Box[source]#

Instantiate from a rasterio window.

Parameters

rio_window (Window) –

Return type

Box

static from_shapely(shape)[source]#

Instantiate from the bounds of a shapely geometry.

geojson_coordinates() List[Tuple[int, int]][source]#

Return Box as GeoJSON coordinates.

Return type

List[Tuple[int, int]]

get_windows(size: Union[PositiveInt, Tuple[PositiveInt, PositiveInt]], stride: Union[PositiveInt, Tuple[PositiveInt, PositiveInt]], padding: Optional[Union[ConstrainedIntValue, Tuple[ConstrainedIntValue, ConstrainedIntValue]]] = None, pad_direction: Literal['both', 'start', 'end'] = 'end') List[Box][source]#

Returns a list of boxes representing windows generated using a sliding window traversal with the specified 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.

Padding currently only applies to the right and bottom edges.

Parameters
  • size (Union[PosInt, Tuple[PosInt, PosInt]]) – Size (h, w) of the windows.

  • stride (Union[PosInt, Tuple[PosInt, PosInt]]) – Step size between windows. Can be 2-tuple (h_step, w_step) or positive int.

  • padding (Optional[Union[PosInt, Tuple[PosInt, PosInt]]], optional) – Optional padding to accommodate windows that overflow the extent. Can be 2-tuple (h_pad, w_pad) or non-negative int. If None, will be set to (size[0]//2, size[1]//2). Defaults to None.

  • pad_direction (Literal['both', 'start', 'end']) – If ‘end’, only pad ymax and xmax (bottom and right). If ‘start’, only pad ymin and xmin (top and left). If ‘both’, pad all sides. Has no effect if padding is zero. Defaults to ‘end’.

Returns

List of Box objects.

Return type

List[Box]

intersection(other: Box) Box[source]#

Return the intersection of this Box and the other.

Parameters

other (Box) – The box to intersect with this one.

Returns

The intersection of this box and the other one.

Return type

Box

intersects(other: Box) bool[source]#
Parameters

other (Box) –

Return type

bool

make_random_box_container(out_h: int, out_w: int) Box[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

Box

make_random_square(size: int) Box[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

Box

make_random_square_container(size: int) Box[source]#

Return a new square Box that contains this Box.

Parameters

size (int) – the width and height of the new Box

Return type

Box

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

Return new square Box.

Return type

Box

normalize() Box[source]#

Ensure ymin <= ymax and xmin <= xmax.

Return type

Box

npbox_format()[source]#

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

Returns

Numpy array of form [ymin, xmin, ymax, xmax] with float type

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

Pad sides by the given amount.

Parameters
  • ymin (int) –

  • xmin (int) –

  • ymax (int) –

  • xmax (int) –

Return type

Box

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) Box[source]#

Reprojects this box based on a transform function.

Parameters

transform_fn (Callable) – A function that takes in a tuple (x, y) and reprojects that point to the target coordinate reference system.

Return type

Box

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: Box) Box[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 (Box) –

Return type

Box

to_int()[source]#
to_local_coords(bbox: Box) Box[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 (Box) –

Return type

Box

static to_npboxes(boxes)[source]#

Return nx4 numpy array from list of Box.

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: Optional[int] = None, w_step: Optional[int] = None) Tuple[slice, slice][source]#

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

Parameters
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) Box[source]#

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

Parameters
Return type

Box

tuple_format() Tuple[int, int, int, int][source]#
Return type

Tuple[int, int, int, int]

static within_aoi(window: Box, aoi_polygons: List[Polygon]) bool[source]#

Check if window is within a list of AOI polygons.

Parameters
Return type

bool

property area: int#

Return area of Box.

property extent: Box#

Return a (0, 0, h, w) Box representing the size of this Box.

property height: int#

Return height of Box.

property size: Tuple[int, int]#
property width: int#

Return width of Box.