Skip to content

Loading Raster Data

UavPy loads raster data into an Orthomosaic artifact. The artifact wraps a georeferenced xarray.DataArray, so later steps can compute indices, crop plots, save GeoTIFFs, or visualize bands without losing geospatial context.

Supported Inputs

The current workflows focus on GeoTIFF orthomosaics and single-band raster stacks.

GDAL and rasterio

Raster loading uses rasterio, which relies on native geospatial libraries. If imports or installs fail, first verify that GDAL is installed and that gdal-config is on PATH.

Large orthomosaic size

UavPy opens GeoTIFFs lazily with rioxarray, so a large orthomosaic does not need to be fully loaded just to inspect metadata. Operations that compute values, plot large rasters, or write Cloud Optimized GeoTIFFs can still read substantial data from disk. For interactive map display, save a GeoTIFF and use mapwidgets.RasterLayer.from_tiled_geotiff().

Load One GeoTIFF

1
2
3
4
from uavpy.artifacts import Orthomosaic

mosaic = Orthomosaic.from_path("./data/orthomosaic.tif")
await mosaic.load()

Inspect the loaded raster:

1
2
3
4
print(mosaic.shape)
print(mosaic.dtype)
print(mosaic.band_info)
print(mosaic.data)

The shape is reported as (band, y, x). For a large orthomosaic, use this metadata to confirm band count and pixel dimensions before choosing bands, extracting plots, or saving map-ready GeoTIFFs.

Display RGB bands. Band numbers passed to plot are one-based:

1
mosaic.plot(rgb=(1, 2, 3), stretch_method="percentiles")

Stack Single-Band Rasters

Use from_paths when each band is stored in a separate raster file. The rasters should have compatible dimensions and geospatial metadata.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
from uavpy.artifacts import Orthomosaic

files = [
    "./data/bands/red.tif",
    "./data/bands/green.tif",
    "./data/bands/blue.tif",
    "./data/bands/nir.tif",
]

mosaic = Orthomosaic.from_paths(files)

The resulting array is shaped as:

1
(band, y, x)

UavPy uses one-based band coordinates in its public plotting and spectral-index APIs. Inspect mosaic.band_info before choosing RGB display bands or index formulas.

Plot One Band

Use band_index to inspect one band at a time. Band indices are one-based.

1
mosaic.plot(band_index=4, cmap="viridis", stretch_method="linear")

Extract Plot-Level Regions

extract_plots crops the orthomosaic by each feature in a ShapeFile and returns one Orthomosaic per feature.

1
2
3
4
5
6
7
8
9
from uavpy.artifacts import ShapeFile

shape_file = ShapeFile("./data/project/shapefiles/march.shp")
plots = await mosaic.extract_plots(shape_file, plot_id_field="plot_id")

for plot in plots:
    print(plot.attrs["plot_id"])
    print(plot.attrs)
    print(plot.shape)

Each returned plot keeps its feature attributes in plot.attrs and uses the same projection as the source orthomosaic.

For file-backed rasters, plot extraction uses rasterio window reads to avoid loading the entire source raster for every feature. Returned plots are pathless Orthomosaic objects with CRS, transform, and spatial coordinates preserved.

Save A GeoTIFF

Use save when you need to persist a loaded, stacked, cropped, or derived orthomosaic back to disk.

1
2
output_path = plots[0].save("./data/outputs/plot_001.tif", overwrite=True)
print(output_path)

save writes .tif or .tiff files, creates parent directories, and raises an error if the raster has no CRS.

Common Issues

Missing file

Orthomosaic.from_path and Orthomosaic.from_paths validate paths before loading. Check relative paths from the current working directory when examples fail with file not found.

Band order

UavPy does not infer semantic band names. If nir=4 is passed to SpectralIndex.ndvi, the fourth band in the raster array is treated as NIR.