How to use the bounding box

Skill level: Beginner

A bounding box specifies the spatial extent of an area of interest given its coordinates in meters:

x_min: minimum x coordinate
y_min: minimum y coordinate
x_max: maximum x coordinate
y_max: maximum y coordinate

View API reference

Open in Google Colab

Open the how-to guide as an interactive notebook in Google Colab or download the notebook to run it locally.

Create a bounding box

You can pass the coordinates to the initializer of the bounding box.

import aviary

bounding_box = aviary.BoundingBox(
    x_min=363084,
    y_min=5715326,
    x_max=363340,
    y_max=5715582,
)

print(bounding_box)

Output

BoundingBox(
    x_min=363084,
    y_min=5715326,
    x_max=363340,
    y_max=5715582,
)

You can access its coordinates using the x_min, y_min, x_max, and y_max attributes.

x_min = bounding_box.x_min
y_min = bounding_box.y_min
x_max = bounding_box.x_max
y_max = bounding_box.y_max

print(x_min)
print(y_min)
print(x_max)
print(y_max)

Output

The bounding box is an iterable object, so it supports indexing and iterating.

You can access its coordinates using the index operator.

x_min = bounding_box[0]
y_min = bounding_box[1]
x_max = bounding_box[2]
y_max = bounding_box[3]

print(x_min)
print(y_min)
print(x_max)
print(y_max)

Output

You can also unpack its coordinates.

x_min, y_min, x_max, y_max = bounding_box

print(x_min)
print(y_min)
print(x_max)
print(y_max)

Output

You can iterate over its coordinates.

for coordinate in bounding_box:
    print(coordinate)

Output

The bounding box exposes its area via the area attribute.

area = bounding_box.area

print(area)

Output

Create a bounding box from a geodataframe

You can create a bounding box from a geodataframe using the from_gdf class method.

from shapely.geometry import box

gdf = gpd.GeoDataFrame(
    geometry=[box(363084, 5715326, 363340, 5715582)],
    crs='EPSG:25832',
)
bounding_box = aviary.BoundingBox.from_gdf(gdf=gdf)

print(bounding_box)

Output

BoundingBox(
    x_min=363084,
    y_min=5715326,
    x_max=363340,
    y_max=5715582,
)

The geodataframe may contain multiple polygons, e.g., the districts of Gelsenkirchen.

url = (
    'https://raw.githubusercontent.com/geospaitial-lab/aviary/main/docs'
    '/how_to_guides/api/data/districts.geojson'
)
gdf = gpd.read_file(url)
bounding_box = aviary.BoundingBox.from_gdf(gdf=gdf)

print(bounding_box)

Output

BoundingBox(
    x_min=360695,
    y_min=5705001,
    x_max=371763,
    y_max=5721922,
)

Intersect bounding boxes

You can intersect two bounding boxes using the & operator.

bounding_box_1 = aviary.BoundingBox(
    x_min=363084,
    y_min=5715326,
    x_max=363340,
    y_max=5715582,
)
bounding_box_2 = aviary.BoundingBox(
    x_min=363212,
    y_min=5715454,
    x_max=363468,
    y_max=5715710,
)

print(bounding_box_1)
print(bounding_box_2)

Output

BoundingBox(
    x_min=363084,
    y_min=5715326,
    x_max=363340,
    y_max=5715582,
)
BoundingBox(
    x_min=363212,
    y_min=5715454,
    x_max=363468,
    y_max=5715710,
)

bounding_box = bounding_box_1 & bounding_box_2

print(bounding_box)

Output

BoundingBox(
    x_min=363212,
    y_min=5715454,
    x_max=363340,
    y_max=5715582,
)

Unite bounding boxes

You can unite two bounding boxes using the | operator.

bounding_box_1 = aviary.BoundingBox(
    x_min=363084,
    y_min=5715326,
    x_max=363340,
    y_max=5715582,
)
bounding_box_2 = aviary.BoundingBox(
    x_min=363212,
    y_min=5715454,
    x_max=363468,
    y_max=5715710,
)

print(bounding_box_1)
print(bounding_box_2)

Output

BoundingBox(
    x_min=363084,
    y_min=5715326,
    x_max=363340,
    y_max=5715582,
)
BoundingBox(
    x_min=363212,
    y_min=5715454,
    x_max=363468,
    y_max=5715710,
)

bounding_box = bounding_box_1 | bounding_box_2

print(bounding_box)

Output

BoundingBox(
    x_min=363084,
    y_min=5715326,
    x_max=363468,
    y_max=5715710,
)

Buffer the bounding box

You can expand the bounding box using the buffer method.

bounding_box = aviary.BoundingBox(
    x_min=363084,
    y_min=5715326,
    x_max=363340,
    y_max=5715582,
)

print(bounding_box)

Output

BoundingBox(
    x_min=363084,
    y_min=5715326,
    x_max=363340,
    y_max=5715582,
)

buffered_bounding_box = bounding_box.buffer(buffer_size=64)

print(buffered_bounding_box)

Output

BoundingBox(
    x_min=363020,
    y_min=5715262,
    x_max=363404,
    y_max=5715646,
)

You can also shrink the bounding box using the buffer method.

bounding_box = aviary.BoundingBox(
    x_min=363084,
    y_min=5715326,
    x_max=363340,
    y_max=5715582,
)

print(bounding_box)

Output

BoundingBox(
    x_min=363084,
    y_min=5715326,
    x_max=363340,
    y_max=5715582,
)

buffered_bounding_box = bounding_box.buffer(buffer_size=-64)

print(buffered_bounding_box)

Output

BoundingBox(
    x_min=363148,
    y_min=5715390,
    x_max=363276,
    y_max=5715518,
)

Snap the bounding box

You can align the bounding box to a grid with the snap method.

bounding_box = aviary.BoundingBox(
    x_min=363084,
    y_min=5715326,
    x_max=363340,
    y_max=5715582,
)

print(bounding_box)

Output

BoundingBox(
    x_min=363084,
    y_min=5715326,
    x_max=363340,
    y_max=5715582,
)

snapped_bounding_box = bounding_box.snap(value=128)

print(snapped_bounding_box)

Output

BoundingBox(
    x_min=363008,
    y_min=5715200,
    x_max=363392,
    y_max=5715584,
)

Convert the bounding box to a geodataframe

You can convert the bounding box to a geodataframe using the to_gdf method.

bounding_box = aviary.BoundingBox(
    x_min=363084,
    y_min=5715326,
    x_max=363340,
    y_max=5715582,
)

print(bounding_box)

Output

BoundingBox(
    x_min=363084,
    y_min=5715326,
    x_max=363340,
    y_max=5715582,
)

gdf = bounding_box.to_gdf(epsg_code=25832)

print(gdf)

Output

                                            geometry
0  POLYGON ((363340 5715326, 363340 5715582, 3630...