How to use the bounding box

Follow along this step-by-step guide to learn about the BoundingBox.

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

A bounding box specifies the spatial extent of an area of interest.

You can pass the coordinates to the initializer of the BoundingBox.
You can access the coordinates of the bounding box with the x_min, y_min, x_max and y_max attributes.

import aviary

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

print(bounding_box.x_min)
print(bounding_box.y_min)
print(bounding_box.x_max)
print(bounding_box.y_max)

Output

We can visualize the bounding box.

You can set the coordinates of an already created bounding box with the x_min, y_min, x_max and y_max attributes.

bounding_box.x_min = 363148
bounding_box.y_min = 5715390
bounding_box.x_max = 363276
bounding_box.y_max = 5715518

print(bounding_box.x_min)
print(bounding_box.y_min)
print(bounding_box.x_max)
print(bounding_box.y_max)

Output

We can visualize the bounding box.

A bounding box is an iterable object, so it supports indexing, length and iteration.

You can access the coordinates of the bounding box with 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

A bounding box has a length, which is obviously 4.

print(len(bounding_box))

Output

You can iterate over the coordinates of the bounding box.

for coordinate in bounding_box:
    print(coordinate)

Output

Create a bounding box from a geodataframe

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

import geopandas as gpd
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.x_min)
print(bounding_box.y_min)
print(bounding_box.x_max)
print(bounding_box.y_max)

Output

We can visualize the bounding box.
The red polygon represents the geodataframe.

The geodataframe may contain multiple polygons, e.g. the northern 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.x_min)
print(bounding_box.y_min)
print(bounding_box.x_max)
print(bounding_box.y_max)

Output

We can visualize the bounding box.
The red polygons represent the districts.

Buffer the bounding box

You can expand the bounding box with the buffer method.

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

print(bounding_box.x_min)
print(bounding_box.y_min)
print(bounding_box.x_max)
print(bounding_box.y_max)

Output

buffered_bounding_box = bounding_box.buffer(buffer_size=64)

print(buffered_bounding_box.x_min)
print(buffered_bounding_box.y_min)
print(buffered_bounding_box.x_max)
print(buffered_bounding_box.y_max)

Output

We can visualize the bounding box.
The red polygon represents the original bounding box.

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

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

print(bounding_box.x_min)
print(bounding_box.y_min)
print(bounding_box.x_max)
print(bounding_box.y_max)

Output

buffered_bounding_box = bounding_box.buffer(buffer_size=-64)

print(buffered_bounding_box.x_min)
print(buffered_bounding_box.y_min)
print(buffered_bounding_box.x_max)
print(buffered_bounding_box.y_max)

Output

We can visualize the bounding box.
The red polygon represents the original bounding box.

Quantize the bounding box

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

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

print(bounding_box.x_min)
print(bounding_box.y_min)
print(bounding_box.x_max)
print(bounding_box.y_max)

Output

quantized_bounding_box = bounding_box.quantize(value=128)

print(quantized_bounding_box.x_min)
print(quantized_bounding_box.y_min)
print(quantized_bounding_box.x_max)
print(quantized_bounding_box.y_max)

Output

We can visualize the bounding box.
The red polygon represents the original bounding box.

Convert the bounding box to a geodataframe

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

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

print(bounding_box.x_min)
print(bounding_box.y_min)
print(bounding_box.x_max)
print(bounding_box.y_max)

Output

gdf = bounding_box.to_gdf(epsg_code=25832)

print(gdf)

Output

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