rastr 0.11.0

Geospatial Raster datatype library for Python.

rastr

A lightweight geospatial raster datatype library for Python focused on simplicity.

For more details, read the documentation: https://rastr.readthedocs.io/en/latest/.

Overview

rastr provides an intuitive interface for creating, reading, manipulating, and exporting geospatial raster data in Python.

Features

• 🧮 Complete raster arithmetic: Full support for mathematical operations (+, -, *, /) between rasters and scalars.
• 📊 Flexible visualization: Built-in plotting with matplotlib and interactive mapping with folium.
• 🗺️ Geospatial analysis tools: Contour generation, Gaussian blurring, and spatial sampling.
• 🛠️ Data manipulation: Fill NaN values, extrapolate missing data, and resample to different resolutions.
• 🔗 Seamless integration: Works with GeoPandas, rasterio, and the broader Python geospatial ecosystem.
• ↔️ Vector-to-raster workflows: Convert GeoDataFrame polygons, points, and lines to raster format.

Installation

# With uv
uv add rastr

# With pip
pip install rastr

Quick Start

from pyproj.crs.crs import CRS
from rasterio.transform import from_origin
from rastr import Raster, RasterMeta
from rastr.create import full_raster


# Create an example raster
raster = Raster.example()

# Write to and read from a file
raster.to_file("raster.tif")
raster = Raster.read_file("raster.tif")

# Basic arithmetic operations
doubled = raster * 2
summed = raster + 10
combined = raster + doubled

# Create full rasters with specified values
cell_size = 1.0
empty_raster = full_raster(
    RasterMeta(
        cell_size=cell_size,
        crs=CRS.from_epsg(2193),
        transform=from_origin(0, 100, cell_size, cell_size),
    ),
    bounds=(0, 0, 100, 100),
    fill_value=0.0,
)

# Visualize the data
ax = raster.plot(cbar_label="Values")

# Interactive web mapping (requires folium)
m = raster.explore(opacity=0.8, colormap="plasma")

# Sample values at specific coordinates
xy_points = [(100.0, 200.0), (150.0, 250.0)]
values = raster.sample(xy_points)

# Generate contour lines
contours = raster.contour(levels=[0.1, 0.5, 0.9], smoothing=True)

# Apply spatial operations
blurred = raster.blur(sigma=2.0)  # Gaussian blur
filled = raster.extrapolate(method="nearest")  # Fill NaN values via nearest-neighbours
resampled = raster.resample(cell_size=0.5)  # Change resolution

# Export to file
raster.to_file("output.tif")

# Convert to GeoDataFrame for vector analysis
gdf = raster.as_geodataframe(name="elevation")

Limitations

Current version limitations:

• Only Single-band rasters are supported.
• In-memory processing only (streaming support planned).
• Square cells only (rectangular cell support planned).
• Only float dtypes (integer support planned).

Similar Projects

• rasters is a project with similar goals of providing a dedicated raster datatype in Python with higher-level interfaces for GIS operations. Unlike rastr, it has support for multi-band rasters, and has some more advanced functionality for Earth Science applications. Both projects are relatively new and under active development.
• rasterio is a core dependency of rastr and provides low-level raster I/O and processing capabilities.
• rioxarray extends xarray for raster data with geospatial support via rasterio.

Contributing

See the CONTRIBUTING.md file.