API Reference¶

This page summarizes the public API that most UavPy workflows use. It is a manual reference grounded in the current package modules, not an autogenerated stub page.

Artifacts¶

Import artifact classes from uavpy.artifacts:

from uavpy.artifacts import DSM, DTM, GeoJsonGeometry, Orthomosaic, ShapeFile, ShpFeature

Orthomosaic¶

Orthomosaic wraps a georeferenced xarray.DataArray with dimensions ordered as (band, y, x). It preserves raster metadata through loading, band stacking, spectral-index results, plot extraction, saving, and plotting.

Constructors:

Orthomosaic.from_path(path, *, chunks=None, target_crs=None, **open_rasterio_kwargs) opens one GeoTIFF lazily through rioxarray.
Orthomosaic.from_paths(paths, *, chunks=None, target_crs=None, **open_rasterio_kwargs) stacks one or more raster files along the band dimension.
Orthomosaic.from_data(data) wraps an existing georeferenced xarray.DataArray.

Common properties and methods:

data exposes the wrapped xarray.DataArray.
attrs, rio, shape, dtype, chunks, source_path, and target_crs expose raster metadata.
band_info returns one dictionary per band with band and name keys.
load(target_crs=None) loads or reprojects raster data asynchronously.
min(..., as_dataarray=False) and max(..., as_dataarray=False) summarize raster values.
plot(rgb=None, band_index=None, cmap="viridis", stretch_method="percentiles", ...) renders RGB or single-band data.
save(path, *, overwrite=False, dtype=None, **profile_options) writes a GeoTIFF.
save_cog(path, *, overwrite=False, compress="DEFLATE", blocksize=512, ...) writes a Cloud Optimized GeoTIFF.
optimize_for_tiling(path, *, overwrite=False, ...) prepares a raster for faster tile reads.
extract_plots(shape_file, plot_id_field, *, all_touched=False, drop=True, invert=False) returns one Orthomosaic per vector feature.

Example:

from uavpy.artifacts import Orthomosaic

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

print(mosaic.shape)
print(mosaic.band_info)

mosaic.plot(rgb=(1, 2, 3))
mosaic.save("outputs/orthomosaic_copy.tif", overwrite=True)

ShapeFile¶

ShapeFile is a lazy vector artifact for shapefile-backed plot boundaries and map overlays.

Constructor:

shape_file = ShapeFile("plots.shp", target_crs="EPSG:4326")

Common properties and methods:

gdf returns the loaded GeoPandas GeoDataFrame, reading from disk on first access.
load(target_crs=None, **read_file_kwargs) loads the file asynchronously.
read(target_crs=None, **read_file_kwargs) loads or reloads the file synchronously.
geojson, bounds, and crs expose vector metadata.
columns() returns attribute column names.
require_column(column) validates that an attribute exists.
features() converts GeoDataFrame features into ShpFeature models.
map_elements() converts supported geometries into Marker, Polyline, or Polygon map schemas.

Example:

from uavpy.artifacts import ShapeFile

shape_file = ShapeFile("plots.shp", target_crs="EPSG:4326")
await shape_file.load()

print(shape_file.columns())
print(shape_file.bounds)

Spectral Tools¶

Import spectral tools from uavpy.tools:

from uavpy.tools import SpectralIndex

SpectralIndex is a callable band-math expression. Band references and built-in helper arguments use one-based band numbers.

Built-in constructors:

SpectralIndex.ndvi(nir, red)
SpectralIndex.gndvi(nir, green)
SpectralIndex.ndre(nir, red_edge)
SpectralIndex.ndwi(green, nir)
SpectralIndex.ndmi(nir, swir)
SpectralIndex.savi(nir, red, soil_brightness=0.5)
SpectralIndex.osavi(nir, red, soil_brightness=0.16)
SpectralIndex.msavi2(nir, red)
SpectralIndex.evi(nir, red, blue, gain=2.5, c1=6.0, c2=7.5, canopy=1.0)
SpectralIndex.evi2(nir, red, gain=2.5, c=2.4, canopy=1.0)
SpectralIndex.wdvi(nir, red, slope=1.16)
SpectralIndex.dvi(nir, red)
SpectralIndex.rvi(nir, red)
SpectralIndex.ci_green(nir, green)
SpectralIndex.ci_red_edge(nir, red_edge)
SpectralIndex.mtci(nir, red_edge, red)
SpectralIndex.sipi(nir, red, blue)
SpectralIndex.vari(green, red, blue)
SpectralIndex.gli(green, red, blue)
SpectralIndex.exg(green, red, blue)

Custom expressions:

from uavpy.tools import SpectralIndex

custom = SpectralIndex("B1 / (B1 + B2 + B3)")
custom_raster = await custom(mosaic)

Calling a SpectralIndex with an Orthomosaic returns a single-band Orthomosaic, so the result can be plotted, saved, cropped, or displayed by saving a GeoTIFF for mapwidgets.

Interactive Map APIs¶

Interactive map viewers, raster layers, vector layers, and map element schemas are provided by the external mapwidgets package. UavPy does not wrap these APIs; import map viewers and layers directly from mapwidgets.

from mapwidgets import MapViewer, RasterLayer, VectorLayer

Example:

from pathlib import Path
import sys

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

tile_layer = RasterLayer.from_tiled_geotiff(
    "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()

mapwidgets.MapViewer¶

MapViewer is provided by the external mapwidgets package. The default backend="maplibre" path does not require a map-service API key. Use backend="google" with an explicit API key when Google Maps is required.

Common methods:

add_layer(layer, zoom_to=False) adds raster or vector layers.
add_tile_overlay(tile_layer) adds raster tile metadata directly.
add_marker(marker), add_polyline(polyline), and add_polygon(polygon) add map element schemas.
fit_bounds(bounds) fits the viewport to WGS84 bounds.
wait_for_map_ready() blocks until the frontend map has initialized.

Vector shapefiles can be displayed through mapwidgets.VectorLayer:

import sys

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

app = QApplication.instance() or QApplication(sys.argv[:1])
viewer = MapViewer(backend="maplibre").resize(1200, 800).show()
viewer.add_layer(
    VectorLayer.from_shapefile("plots.shp", id="plots", name="Plot boundaries"),
    zoom_to=True,
)
viewer.wait_for_map_ready()
app.exec()

Utility Modules¶

Import utility classes from uavpy.util:

from uavpy.util import ArrayUtil, MathUtil, MiscUtil, RasterioUtil, VisualizationUtil

GDALUtil is loaded lazily because GDAL's Python bindings require native shared libraries to be available at import time:

from uavpy.util import GDALUtil

Use these helpers for array normalization, display scaling, rasterio metadata operations, GDAL-backed conversions, and small camera-geometry calculations.