Skip to content

UavPy

Code style: black Contributions welcome

UavPy is a Python package for processing and analyzing UAV imagery. It provides a small, high-level API for loading orthomosaics, stacking raster bands, computing spectral indices, extracting plot-level regions of interest, and visualizing geospatial raster data.

The package builds on GDAL, rasterio, Fiona, NumPy, SciPy, and scikit-image.

What You Can Do

  • Load a GeoTIFF orthomosaic into an Orthomosaic artifact.
  • Stack multiple single-band rasters into one multi-band raster.
  • Compute NDVI, NDRE, EVI, SAVI, WDVI, and custom band-math expressions.
  • Extract one georeferenced orthomosaic per polygon feature from a vector file.
  • Save processed rasters as GeoTIFFs for map display.
  • Display raster tile layers and vector layers with mapwidgets.MapViewer.

See Runnable Examples for focused scripts that cover loading, plot extraction, spectral indices, and interactive maps.

Requirements

UavPy requires Python 3.10 or newer.

GDAL is a native dependency. The Python GDAL package must match the native GDAL library available on the machine. This checkout currently pins:

1
gdal==3.13.1

On macOS with Homebrew GDAL, make sure gdal-config is on PATH before installing:

1
PATH="/opt/homebrew/bin:$PATH" uv sync

GDAL version matching

If uv sync fails with a message like Python bindings of GDAL ... require at least libgdal ..., update the Python gdal dependency to match the version reported by gdal-config --version, or update the native GDAL installation to match the pinned Python package.

Install For Development

1
PATH="/opt/homebrew/bin:$PATH" uv sync

Run tests:

1
PATH="/opt/homebrew/bin:$PATH" uv run pytest

Serve the docs locally:

1
PATH="/opt/homebrew/bin:$PATH" uv run mkdocs serve

Build the static docs:

1
PATH="/opt/homebrew/bin:$PATH" uv run mkdocs build

Install the optional map viewer dependencies when using mapwidgets.MapViewer:

1
PATH="/opt/homebrew/bin:$PATH" uv sync --extra widgets

Quick Start

Load a single orthomosaic:

1
2
3
4
5
from uavpy.artifacts import Orthomosaic

mosaic = Orthomosaic.from_path("./data/orthomosaic.tif")
await mosaic.load()
mosaic.plot(rgb=(1, 2, 3), stretch_method="percentiles")

Stack single-band rasters:

1
2
3
4
5
6
7
8
9
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)

Compute NDVI:

1
2
3
4
5
from uavpy.tools import SpectralIndex

ndvi = SpectralIndex.ndvi(nir=4, red=1)
ndvi_map = await ndvi(mosaic)
ndvi_map.plot(band_index=1, cmap="hsv", stretch_method="linear")

Compute a custom index:

1
2
3
index = SpectralIndex("B1 / (B1 + B2 + B3)")
index_raster = await index(mosaic)
index_raster.plot(band_index=1)

Create map tiles with mapwidgets and add them to an interactive map:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
from pathlib import Path
import sys

from mapwidgets import MapViewer, RasterLayer
from PySide6.QtWidgets import QApplication

tile_layer = RasterLayer.from_tiled_geotiff(
    "./data/rgb_orthomosaic.tif",
    output_dir=Path(".uavpy_tiles/rgb"),
    bands=(1, 2, 3),
    zoom_levels=range(18, 22),
    backend="gdal",
    overwrite=True,
)

app = QApplication.instance() or QApplication(sys.argv[:1])
viewer = MapViewer(backend="maplibre").resize(1200, 800).show()
viewer.add_layer(tile_layer, zoom_to=True)
viewer.wait_for_map_ready()
app.exec()

Extract plot-level rasters:

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

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

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

Project Layout

  • uavpy/artifacts - Raster and vector artifact classes such as Orthomosaic, DSM, DTM, and ShapeFile.
  • uavpy/tools - Spectral index and expression parsing tools.
  • uavpy/util - Raster, array, math, GDAL, rasterio, and visualization utilities.
  • uavpy/decor - Internal decorator helpers.
  • tests - Test suite.
  • mkdocs - Documentation source.
  • docs - Built static documentation output.

Useful Commands

  • uv sync - Install the project and development dependencies.
  • uv run pytest - Run the test suite.
  • uv run mkdocs serve - Start the live-reloading docs server.
  • uv run mkdocs build - Build the static documentation site.

Citation

1
2
3
4
5
6
7
@software{uavpy,
    author = {Henry Ruiz},
    title = {UavPy: High level Python API for UAV imagery processing},
    url = {https://github.com/haruiz/uavpy},
    version = {0.1.0},
    year = {2020},
}