Current release info

Name	Downloads	Version	Platforms

conda-forge feedstock

Conda-forge feedstock

pyramids - GIS utility package

pyramids is a GIS utility package built on top of GDAL/OGR for working with raster data (GeoTIFF, NetCDF), vector data (shapefiles, GeoJSON), and multi-temporal datacubes.

graph LR
    GeoTIFF & NetCDF & Shapefile & UGRID -->|read| pyramids
    subgraph pyramids
        Dataset
        NetCDF_class[NetCDF]
        UgridDataset
        DatasetCollection
        FeatureCollection
    end
    Dataset -->|crop · reproject · align| Dataset
    FeatureCollection -->|rasterize| Dataset
    UgridDataset -->|interpolate| Dataset
    Dataset -->|vectorize| FeatureCollection
    DatasetCollection -->|temporal stack| Dataset
    NetCDF_class -->|extends| Dataset

Loading

For detailed architecture diagrams, see docs/overview/architecture.md.

Main Features

• Dataset - Read, write, crop, reproject, and align single-band and multi-band rasters (GeoTIFF) with full no-data handling and coordinate reference system support.
• NetCDF - Extends Dataset for NetCDF files with time/variable dimensions and CF conventions metadata. Optional xarray interoperability.
• UgridDataset - Read and visualize UGRID-1.0 unstructured meshes (triangles, quads, mixed). Supports mesh-to-raster interpolation and mesh-to-vector export.
• DatasetCollection - Manage time-series of co-registered rasters as a temporal stack for multi-temporal analysis.
• FeatureCollection - Work with vector data (shapefiles, GeoJSON) through a unified GeoDataFrame and OGR DataSource interface, including rasterization and geometry operations.
• Spatial operations - Align rasters to a reference grid, reproject between coordinate systems, crop to vector boundaries, and convert between raster, NetCDF, and vector formats.

Installing pyramids

Installing pyramids from the conda-forge channel can be achieved by:

conda install -c conda-forge pyramids

It is possible to list all the versions of pyramids available on your platform with:

conda search pyramids --channel conda-forge

Install from GitHub

To install the latest development version, you can install the library from GitHub:

pip install git+https://github.com/serapeum-org/pyramids

pip

To install the latest release from PyPI:

pip install pyramids-gis

Optional extras

pip install pyramids-gis[viz]      # cleopatra plotting support
pip install pyramids-gis[xarray]   # xarray/NetCDF4 interoperability

Quick start

from pyramids.dataset import Dataset

# Open a raster file
src = Dataset.read_file("path/to/raster.tif")
print(src.epsg)        # coordinate reference system EPSG code
print(src.cell_size)   # pixel resolution
print(src.shape)       # (rows, columns)

# Get the raster data as a NumPy array
arr = src.raster.ReadAsArray()

from pyramids.netcdf import NetCDF

# Open a NetCDF file
nc = NetCDF.read_file("path/to/data.nc")
print(nc.variables)

from pyramids.feature import FeatureCollection

# Open a vector file
vector = FeatureCollection.read_file("path/to/shapefile.shp")
print(vector.shape)

Testing

This project uses pixi as the environment and task manager.

# Install dependencies and create dev environment
pixi install -e dev

# Run all tests (excluding plot tests)
pixi run -e dev main

# Run plot tests only
pixi run -e dev plot

# Run a specific test file
pixi run -e dev pytest tests/netcdf/test_dimensions.py -v

# Run a single test by node id
pixi run -e dev pytest tests/netcdf/test_dimensions.py::TestStripBraces::test_with_braces -q

Docker

A Dockerfile is provided to run pyramids-gis in a controlled environment with the correct GDAL stack preinstalled via conda-forge. The image uses a multi-stage pixi build for a minimal production container.

Build the image:

docker build -t pyramids-gis:latest .

Run the container (mount your current folder as /workspace):

docker run --rm -it -v ${PWD}:/workspace pyramids-gis:latest bash

Inside the container you can verify the package is installed:

python -c "import pyramids; print('pyramids', pyramids.__version__)"