pyramids — GIS utilities for rasters, vectors & datacubes, built on GDAL/OGR

GitHub last commit GitHub Repo stars

GitHub commits since latest release (by SemVer including pre-releases)

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.

pyramids at a glance — every GDAL format, none of the boilerplate

pyramids-gis is licensed under GPLv3 (see LICENSE.md). The platform wheels published on PyPI bundle GDAL and its native dependencies (PROJ, GEOS, libtiff, NetCDF-C, HDF5, libcurl, …) — each under its own MIT, BSD, LGPL, or Apache license. The full attribution list and shipped license texts are documented in THIRD_PARTY_LICENSES.md; if you use pyramids-gis in publications please also cite GDAL itself per gdal.org/cite_gdal.html.

graph LR
    GeoTIFF & NetCDF & Shapefile & UGRID -->|read| pyramids
    subgraph pyramids
        direction TB
        Dataset
        NetCDF_class[NetCDF]
        UgridDataset
        DatasetCollection
        FeatureCollection
        subgraph Engines["Dataset engines (ds.io · ds.spatial · ds.bands · ds.analysis · ds.cell · ds.vectorize · ds.cog)"]
        end
        subgraph Plotting["Plotting layer — _plot_helpers.render_array · mesh_render · NetCDFPlot · Selectors / ColourOpts / FacetSpec · basemap"]
        end
    end
    Dataset -->|crop · reproject · align| Dataset
    Dataset --- Engines
    FeatureCollection -->|rasterize| Dataset
    UgridDataset -->|interpolate| Dataset
    Dataset -->|vectorize| FeatureCollection
    DatasetCollection -->|lazy temporal stack| Dataset
    NetCDF_class -->|extends| Dataset
    Dataset & NetCDF_class & DatasetCollection & UgridDataset -->|plot| Plotting
    Plotting -->|delegates| cleopatra(["cleopatra<br/>ArrayGlyph · MeshGlyph · tiles"])

For the class relationships, internal layers, and 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. Public API is organized into seven engine collaborators (ds.io, ds.spatial, ds.bands, ds.analysis, ds.cell, ds.vectorize, ds.cog); same-named facade methods on the Dataset itself keep the short form working — ds.crop(mask) and ds.spatial.crop(mask) are equivalent.
NetCDF - Extends Dataset for NetCDF files with time/variable dimensions and CF conventions metadata. Optional labeled-array interoperability. NetCDF.plot exposes a labeled-array-style plotting API (variable= + grouped Selectors / ColourOpts / FacetSpec dataclasses, curvilinear coords=, kind=, animate=, lazy chunks=).
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 lazy temporal stack (per-timestep gdal handles open on demand; the full cube is never materialised in RAM) with optional dask-backed reductions and groupby.
FeatureCollection - Work with vector data (shapefiles, GeoJSON) through a unified GeoDataFrame and OGR DataSource interface, including rasterization and geometry operations.
Plotting - Dataset / NetCDF / DatasetCollection / UgridDataset all expose a plot method backed by cleopatra (the [viz] extra), routed through a shared pyramids.dataset._plot_helpers core. Optional web-tile basemap underlays via pyramids.basemap.add_basemap (a thin wrapper over cleopatra.tiles.add_tiles).
Cloud-Optimized GeoTIFF (COG) - First-class read/write/validate support via ds.to_cog, ds.is_cog, and ds.validate_cog.
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 (development)

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

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

Note: installing from GitHub uses the sdist and requires a pre-installed system GDAL. See the full installation guide and troubleshooting for details.

pip

To install the latest release from PyPI:

pip install pyramids-gis

Linux + pixi: no glibc pin needed anymore

pyramids-gis ships its Linux wheels tagged manylinux_2_28 (GDAL and its native stack are compiled from source with the manylinux toolchain). pixi's default Linux baseline is glibc 2.28 (it tracks conda-forge's floor), so the wheel resolves out of the box — no [tool.pixi.system-requirements] entry required (verified with pixi 0.65 defaults; newer versions, including the 0.68.1 this repo pins in CI, share the same baseline).

Two cases still need a pin in the consuming project's pyproject.toml / pixi.toml:

[tool.pixi.system-requirements]
libc = "2.39"    # only for the older releases that shipped manylinux_2_39 wheels (0.2x-0.39.x)

or libc = "2.28" if you run a pixi version old enough that its default baseline is still below 2.28. On Linux with glibc < 2.28, install from conda-forge instead. See the full installation guide and troubleshooting for the other cases.

Optional extras

pip install pyramids-gis[viz]      # cleopatra plotting support
pip install xarray                 # to_xarray / from_xarray / to_netcdf interop (peer dep, not an extra)

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)       # (bands, rows, columns)

# Read the raster data as a NumPy array
arr = src.read_array()                  # all bands
band0 = src.read_array(band=0)          # one band

# Spatial ops route through the spatial engine; the facade stays short
reprojected = src.to_crs(to_epsg=3857)  # same as src.spatial.to_crs(...)

from pyramids.netcdf import NetCDF
from pyramids import Selectors, ColourOpts, FacetSpec   # grouped plot options

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

# labeled-array-style plotting (needs the [viz] extra)
nc.plot("t2m", selectors=Selectors(time="2020-07-01", level=850),
        colour=ColourOpts(cmap="coolwarm", robust=True))
nc.plot("t2m", facet=FacetSpec(col="time", col_wrap=4))   # small multiples
nc.plot("t2m", animate="time", chunks={"time": 1})        # lazy per-frame animation

from pyramids.feature import FeatureCollection

# Open a vector file
vector = FeatureCollection.read_file("path/to/shapefile.shp")
print(vector.epsg)            # CRS EPSG code
print(vector.total_bounds)    # (minx, miny, maxx, maxy)

from pyramids.dataset import DatasetCollection

# Build a lazy stack of co-registered rasters (no pixels read yet)
cube = DatasetCollection.from_files(["a.tif", "b.tif", "c.tif"])
print(cube.time_length, cube.shape)

# Reductions over the time axis use dask under the hood
mean = cube.mean()                       # nan-aware by default

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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyramids_gis-0.59.0.tar.gz (1.1 MB view details)

Uploaded Sep 2, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

pyramids_gis-0.59.0-cp314-cp314-win_arm64.whl (26.9 MB view details)

Uploaded Sep 2, 2026 CPython 3.14Windows ARM64

pyramids_gis-0.59.0-cp314-cp314-win_amd64.whl (52.4 MB view details)

Uploaded Sep 2, 2026 CPython 3.14Windows x86-64

pyramids_gis-0.59.0-cp314-cp314-manylinux_2_28_x86_64.whl (32.1 MB view details)

Uploaded Sep 2, 2026 CPython 3.14manylinux: glibc 2.28+ x86-64

pyramids_gis-0.59.0-cp314-cp314-manylinux_2_28_aarch64.whl (30.6 MB view details)

Uploaded Sep 2, 2026 CPython 3.14manylinux: glibc 2.28+ ARM64

pyramids_gis-0.59.0-cp314-cp314-macosx_11_0_x86_64.whl (46.8 MB view details)

Uploaded Sep 2, 2026 CPython 3.14macOS 11.0+ x86-64

pyramids_gis-0.59.0-cp314-cp314-macosx_11_0_arm64.whl (43.6 MB view details)

Uploaded Sep 2, 2026 CPython 3.14macOS 11.0+ ARM64

pyramids_gis-0.59.0-cp313-cp313-win_arm64.whl (26.2 MB view details)

Uploaded Sep 2, 2026 CPython 3.13Windows ARM64

pyramids_gis-0.59.0-cp313-cp313-win_amd64.whl (50.8 MB view details)

Uploaded Sep 2, 2026 CPython 3.13Windows x86-64

pyramids_gis-0.59.0-cp313-cp313-manylinux_2_28_x86_64.whl (32.1 MB view details)

Uploaded Sep 2, 2026 CPython 3.13manylinux: glibc 2.28+ x86-64

pyramids_gis-0.59.0-cp313-cp313-manylinux_2_28_aarch64.whl (30.6 MB view details)

Uploaded Sep 2, 2026 CPython 3.13manylinux: glibc 2.28+ ARM64

pyramids_gis-0.59.0-cp313-cp313-macosx_11_0_x86_64.whl (46.8 MB view details)

Uploaded Sep 2, 2026 CPython 3.13macOS 11.0+ x86-64

pyramids_gis-0.59.0-cp313-cp313-macosx_11_0_arm64.whl (43.6 MB view details)

Uploaded Sep 2, 2026 CPython 3.13macOS 11.0+ ARM64

pyramids_gis-0.59.0-cp312-cp312-win_arm64.whl (26.2 MB view details)

Uploaded Sep 2, 2026 CPython 3.12Windows ARM64

pyramids_gis-0.59.0-cp312-cp312-win_amd64.whl (50.8 MB view details)

Uploaded Sep 2, 2026 CPython 3.12Windows x86-64

pyramids_gis-0.59.0-cp312-cp312-manylinux_2_28_x86_64.whl (32.1 MB view details)

Uploaded Sep 2, 2026 CPython 3.12manylinux: glibc 2.28+ x86-64

pyramids_gis-0.59.0-cp312-cp312-manylinux_2_28_aarch64.whl (30.6 MB view details)

Uploaded Sep 2, 2026 CPython 3.12manylinux: glibc 2.28+ ARM64

pyramids_gis-0.59.0-cp312-cp312-macosx_11_0_x86_64.whl (46.8 MB view details)

Uploaded Sep 2, 2026 CPython 3.12macOS 11.0+ x86-64

pyramids_gis-0.59.0-cp312-cp312-macosx_11_0_arm64.whl (43.6 MB view details)

Uploaded Sep 2, 2026 CPython 3.12macOS 11.0+ ARM64

pyramids_gis-0.59.0-cp311-cp311-win_amd64.whl (50.8 MB view details)

Uploaded Sep 2, 2026 CPython 3.11Windows x86-64

pyramids_gis-0.59.0-cp311-cp311-manylinux_2_28_x86_64.whl (32.1 MB view details)

Uploaded Sep 2, 2026 CPython 3.11manylinux: glibc 2.28+ x86-64

pyramids_gis-0.59.0-cp311-cp311-manylinux_2_28_aarch64.whl (30.6 MB view details)

Uploaded Sep 2, 2026 CPython 3.11manylinux: glibc 2.28+ ARM64

pyramids_gis-0.59.0-cp311-cp311-macosx_11_0_x86_64.whl (46.8 MB view details)

Uploaded Sep 2, 2026 CPython 3.11macOS 11.0+ x86-64

pyramids_gis-0.59.0-cp311-cp311-macosx_11_0_arm64.whl (43.6 MB view details)

Uploaded Sep 2, 2026 CPython 3.11macOS 11.0+ ARM64

File details

Details for the file pyramids_gis-0.59.0.tar.gz.

File metadata

Download URL: pyramids_gis-0.59.0.tar.gz
Upload date: Sep 2, 2026
Size: 1.1 MB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pyramids_gis-0.59.0.tar.gz
Algorithm	Hash digest
SHA256	`d592ab3abd3542480efdf6826306203ca437b18a37358be23d7dadc747dac290`
MD5	`18bd8045537ae294e7db7442fdd45ec1`
BLAKE2b-256	`bd3340c646d80f7fbd47f6976cacbe9c8693d89815fcd2ee07309f1161ae8305`

Algorithm	Hash digest
SHA256	`53a05ae8d7ea6573b12fd452f2ad7e972a44453c63e1206da699dd459d5d429f`
MD5	`e88b910799c843b63c1ec42e524115bd`
BLAKE2b-256	`32b3582bd36476924cd7ba6212a241b2e71a83ffc0e1f05b89cd4ffedcd4aac0`

Algorithm	Hash digest
SHA256	`3e70649d773b608716d09a8e5fa70c1cb2860b093b4ad7d72122999f52db62ca`
MD5	`d5060759583bea57c13eba8e04fa9508`
BLAKE2b-256	`294d6cb18a554b637cfb00f3f7858a112061d75dbb64ec2711d716235fe3c7e6`

Algorithm	Hash digest
SHA256	`3276b00ad519eff449b2724262af7bf0c44e7c24ef0cc39746a35c2dcdac2927`
MD5	`732d0b31cf7f664fc910dc9a7d4c1907`
BLAKE2b-256	`f0a6ecc60cc74495d5413a2824114167c1f12963a810b03f4cb50789f2b6d13c`

Algorithm	Hash digest
SHA256	`0df9dda3bac25418dc5a302cacb6970d6fbb8a0b18f1590f22193e4d69bf68e9`
MD5	`9ce3445ac11f9a0ebdd9490effba4279`
BLAKE2b-256	`cbf58e1e309530822cdcbb545208916e5238aa217478d6f230a75135f884dd03`

Algorithm	Hash digest
SHA256	`cb6113f500aadf74ed050ca50f56e9912d9e1b79f6b474196d7400c011518a3c`
MD5	`a0e91ac494855cfc5c1efa09bf615505`
BLAKE2b-256	`4763ed901817c246e613f3b4ef8a6ba441e09b27916a45137158fd68113a2a23`

Algorithm	Hash digest
SHA256	`56c94b57683d8a52a591a5f696bf22330cf907dbef2186ac072251005ba38283`
MD5	`382d3519ed2efda6ff51361202ecbdff`
BLAKE2b-256	`d9e01b83d3bda21cc1fdb7ad0c848980caad3d8e3e63e6721c4027496605a886`

Algorithm	Hash digest
SHA256	`f5a3520576c27ed288de8f9560231c3b4a6bc75f9756da1dad8103464a663323`
MD5	`b8a77d89697133fbdf5546edc7d2b3b7`
BLAKE2b-256	`ad08d054554bebbe950ab2d93c844930b13d3e1bb2b742c4fcd19d8a0708103e`

Algorithm	Hash digest
SHA256	`fc0eca540e740af6b7630eb7f173dd9ca81d8c61eac8fd3114e550c65600e944`
MD5	`b986eb203d07b376f7a06e80842cc559`
BLAKE2b-256	`34bd0d731685290f60a15cf98b903fc6c594c97bbed02ff80eaf24eb94d0369a`

Algorithm	Hash digest
SHA256	`e98cf7e42a5ba94a83b897ef2dd42c6de4a7c8e2d44b4eb30f1c5a223bb72683`
MD5	`41c776f814800112a37afff29adb47f2`
BLAKE2b-256	`0dab8cfdc4e83716c0bbf91f5bfcf0f05bcbf5e3846b13caa38371aaeec82175`

Algorithm	Hash digest
SHA256	`fd542e1935cbe140f5ccc98c6530deab0885f69180c94908784f4d9bfc7161b4`
MD5	`cfe91bce9c56c432260a0b7ac3543da9`
BLAKE2b-256	`c4fbbae1a9e7294fbba8d24ac01cc7ad863c036fbb526d608047b76271b11b0c`

Algorithm	Hash digest
SHA256	`0d91c7760874d79aefdde226415bf5d4d9fbfecbeb3bff84a83c7f0a09470185`
MD5	`b5bfb328e6d78fe7fc8892d27ad74e82`
BLAKE2b-256	`1d63b8d2646c6191882c19f951e3c863d211388fdd695a392364309d793f4347`

Algorithm	Hash digest
SHA256	`bdbf2374c9fdc832cf372c047d7898251cfe99e9216ca21b6701d537d8c2167b`
MD5	`01b579a1c9f5e31c29a3e6f6190959ce`
BLAKE2b-256	`7a3947c6d0be6ca1c991f32361e04f562b26e7ab1e07a8f2e2d7affb865c7695`

Algorithm	Hash digest
SHA256	`b538cba179e4daf6f4926834e136659e58e0934aacb3563317de0d408ef9fac8`
MD5	`bedf59f16912e2ad96edd47d25ac8692`
BLAKE2b-256	`2dd109c793b376157a5bca5a53d53402d7b5adb79e2e20d1859b1d9efc65f85b`

Algorithm	Hash digest
SHA256	`6628a7c39e2906637dc7e6096cb014196a69d96f9111958a119e91b409ff1e57`
MD5	`04599327539d5e365a1062e175b3b677`
BLAKE2b-256	`6ece2bff266da2e3248dd93e27a2e6207b1dd7044ca432d896aebfe80afe907c`

Algorithm	Hash digest
SHA256	`9df501a68f3a7338936fa3bf106c90f5eebc246bc282fdfc6fdb7b9b160df4b0`
MD5	`c0956a9ab68d4e3eeffccbaed435d29d`
BLAKE2b-256	`d9f18ffc022d861a5ee5333249c83ba518c5dadced93e148c8f4c13bad85f05b`

Algorithm	Hash digest
SHA256	`5431890697c00eb3c4b01c49cdc95ebef1ddcdab6ddcc13f768bb9e956f0ce59`
MD5	`7ac63891fc8be6ee1456a621ed16d2c1`
BLAKE2b-256	`7345d9e305769b4ad16cb9e386fa913873eabd32365afd87b030eed3db1bf3dc`

Algorithm	Hash digest
SHA256	`17e2fc6c19a8e5abf4761863b0c2ad617974c1f3701fccea17a22a5bccb3eacc`
MD5	`9036189ea60f4864892702667772ffae`
BLAKE2b-256	`e2c3c956e754fa71b6d34f03b9dfa8d6d46b4fbf5b209737bbf62fe996df6bb3`

Algorithm	Hash digest
SHA256	`135c05f5159ffd5830c69e8343383b7b394b7aa37ef7b84dd5298a386a64b199`
MD5	`bee0434f73352a68b837ac6e55c1ff2c`
BLAKE2b-256	`c816925503a7afd8f684908ebfe5327f6b894dd4af2d2deb1fe0467f26ee26ce`

Algorithm	Hash digest
SHA256	`f2f486f57455c5c7614ca1b3ad1029d9fa23a69b2a89d86b700a03bee415723d`
MD5	`93063e75cdcba2fa53e7fb9409d589ba`
BLAKE2b-256	`a8f5937395584963313b27125e1eab98b9b0735eb4bf5438f8202fa59799a0bc`

Algorithm	Hash digest
SHA256	`02bb518af714d61ad47a08288331649b25396808d5539000d8ccdfdcfc83c49f`
MD5	`4dcf00f89b8e0149a8b54641f141d03b`
BLAKE2b-256	`6858d2f19cf40500ffcf6cfca4f82587f8426efad66235b96fe1e6ba2ecdb742`

pyramids-gis 0.59.0

Current release info

conda-forge feedstock

pyramids - GIS utility package

Main Features

Installing pyramids

Install from GitHub (development)

pip

Linux + pixi: no glibc pin needed anymore

Optional extras

Quick start

Testing

Docker

Project links

Key dates

1 maintainer

Credits

License

Requires

Provides Extra

Tags

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

Algorithm	Hash digest
SHA256	`2596c4678ec04212ecf0d5da776adafbecda180477ba31c3e6070b0deb0281d0`
MD5	`26c8f3e83a24f24460ba1d44b65ffbf8`
BLAKE2b-256	`206641f6c33fe9378a90b55fd64718d53f25d303b873c07d9976c5a184e6688f`

Algorithm	Hash digest
SHA256	`bd799ffa62d551eaaa9b2ee58e33f65bf5f0c41bb05cf5b919dbb68989979e3d`
MD5	`74111b0e5aea42615dd367ce64742801`
BLAKE2b-256	`d65e1d885a6582a4fd235f556ea55892fa47b26d633c1b5490f7b1bf796b6979`

Algorithm	Hash digest
SHA256	`dc200d58d325e167a487c25df0b0425496e91afd51ccf475e300175cf22570a0`
MD5	`844eb3bb699844ca604f77d4a70a68a0`
BLAKE2b-256	`c80eb1eeac4285db450f7992cd96fe909761a756e92cdb013e7154537d41aa5b`