rastr

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

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

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

# 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")

Quick Reference

from rastr import Raster

Data access

• Raster.bbox - bounding box polygon.
• Raster.bounds - bounding box as (xmin, ymin, xmax, ymax).
• Raster.cell_size - cell size.
• Raster.crs - coordinate reference system.
• Raster.origin - grid origin (x, y) of the first pixel corner.
• Raster.shape - raster shape (rows, columns).
• Raster.transform - affine transform.
• Raster.sample(xy) - sample raster values at given coordinates.

I/O

• Raster.read_file(path) - read raster from file.
• Raster.to_file(path) - write raster to file.
• Raster.to_clipboard() - copy raster data to clipboard in a tabular format.

Geometric Operations

• Raster.crop(bounds) - remove cells outside given bounds.
• Raster.pad(width) - add NaN border around raster.
• Raster.resample(cell_size) - resample raster to a new cell size.
• Raster.set_origin(x, y) - set the transform origin without modifying pixel data.
• Raster.taper_border(width) - gradually reduce values to zero at the border.
• Raster.gdf() - Vectorize to a GeoDataFrame of cell polygons and values.

NaN Management and value replacements

• Raster.clip(polygon) - replace values outside a polygon with NaN.
• Raster.extrapolate() - fill NaN values via nearest-neighbours.
• Raster.fillna(value) - fill NaN values with a specified value.
• Raster.replace(to_replace, value) - replace specific cell values.
• Raster.replace_polygon(polygon, value) - replace cell values within a polygon.
• Raster.trim_nan() - remove border rows/columns that are entirely NaN.

Image Processing

• Raster.blur(radius) - apply Gaussian blur.
• Raster.dilate(radius) - apply morphological dilation.
• Raster.sobel() - apply Sobel filter (edge detection/gradient).

Visualization

• Raster.explore() - interactive web map visualization with folium.
• Raster.plot() - matplotlib static plot with colorbar.
• Raster.contour(levels) - get a GeoDataFrame of contour lines.

Cell-wise Operations

• Raster.apply(func) - apply a function to cell values.
• Raster.abs() - absolute value of cell values.
• Raster.astype(dtype) - cast cell values to a specified dtype.
• Raster.clamp() - clip cell values to an (a_min, a_max) range.
• Raster.exp() - exponential of cell values.
• Raster.log() - logarithm of cell values.
• Raster.max() - maximum of cell values.
• Raster.mean() - mean of cell values.
• Raster.median() - median of cell values.
• Raster.min() - minimum of cell values.
• Raster.normalize() - normalize cell values to [0, 1].
• Raster.quantile(q) - quantile of cell values.
• Raster.std() - standard deviation of cell values.
• Raster.sum() - sum of cell values.
• Raster.unique() - array of unique cell values.

Limitations

Current version limitations:

• Only Single-band rasters are supported.
• In-memory processing only (streaming 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.