Current release info
| Name | Downloads | Version | Platforms |
|---|---|---|---|
 |
     |
  |
 |
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-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)andds.spatial.crop(mask)are equivalent. - NetCDF - Extends Dataset for NetCDF files with time/variable dimensions and CF conventions metadata.
Optional labeled-array interoperability.
NetCDF.plotexposes a labeled-array-style plotting API (variable=+ groupedSelectors/ColourOpts/FacetSpecdataclasses, curvilinearcoords=,kind=,animate=, lazychunks=). - 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/UgridDatasetall expose aplotmethod backed by cleopatra (the[viz]extra), routed through a sharedpyramids.dataset._plot_helperscore. Optional web-tile basemap underlays viapyramids.basemap.add_basemap(a thin wrapper overcleopatra.tiles.add_tiles). - Cloud-Optimized GeoTIFF (COG) - First-class read/write/validate support via
ds.to_cog,ds.is_cog, andds.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__)"
1 maintainer
Metadata
1 maintainer
Release files for pyramids-gis 0.68.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
Total release size: 609.5 MB
Release files / pyramids_gis-0.68.0-cp312-cp312-win_arm64.whl
| Download URL | pyramids_gis-0.68.0-cp312-cp312-win_arm64.whl |
|---|---|
| Size | 27.5 MB |
| Tags | CPython 3.12 Windows ARM64 |
|
SHA-256 checksum How to use checksums |
669b15fbfe556d90505a357ff201680efa544052085bc109a56ab328480601d9
|
|
BLAKE2b-256 checksum How to use checksums |
37594cf7c74d8b29c3afd1ef54ea68bafa3d0dc74fa5d1131bbc0beb099535e3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / pyramids_gis-0.68.0-cp312-cp312-win_amd64.whl
| Download URL | pyramids_gis-0.68.0-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 51.6 MB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
d2fb6f5e2eaab894a32e877e6d2d7aec17277eec6ba934cade1d52ecf431ca86
|
|
BLAKE2b-256 checksum How to use checksums |
e448c10689469ffb4752860c58540465d454fea891cbdfe39b6ec229346160f6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / pyramids_gis-0.68.0-cp312-cp312-musllinux_1_2_x86_64.whl
| Download URL | pyramids_gis-0.68.0-cp312-cp312-musllinux_1_2_x86_64.whl |
|---|---|
| Size | 41.2 MB |
| Tags | CPython 3.12 Linux musl 1.2+ x86-64 |
|
SHA-256 checksum How to use checksums |
35143e017335d6cbd2ef9b1332a603561a326992837a1de42e6fca29af6c56ff
|
|
BLAKE2b-256 checksum How to use checksums |
8bf4813bf08a1cdb6211cb5b8db9e417bf50f35fb3056916c076b067043be22f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / pyramids_gis-0.68.0-cp312-cp312-musllinux_1_2_aarch64.whl
| Download URL | pyramids_gis-0.68.0-cp312-cp312-musllinux_1_2_aarch64.whl |
|---|---|
| Size | 39.7 MB |
| Tags | CPython 3.12 Linux musl 1.2+ ARM64 |
|
SHA-256 checksum How to use checksums |
932c820cdb69bbd17bd647494b038ce43e0d357f70e668630fbd602a052fa826
|
|
BLAKE2b-256 checksum How to use checksums |
c977922e14377f524be0b759c34a144a101797c71cc301051c674b3ed8799dda
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / pyramids_gis-0.68.0-cp312-cp312-manylinux_2_28_x86_64.whl
| Download URL | pyramids_gis-0.68.0-cp312-cp312-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 33.0 MB |
| Tags | CPython 3.12 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
bb73e7a80d3718d8bf56f6b765f39d89c413750128038dd6494a9aff2be856ad
|
|
BLAKE2b-256 checksum How to use checksums |
07f13303b3a8531dc7966c8fc02e11f274d217d89238c42522cec2613380ad24
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / pyramids_gis-0.68.0-cp312-cp312-manylinux_2_28_aarch64.whl
| Download URL | pyramids_gis-0.68.0-cp312-cp312-manylinux_2_28_aarch64.whl |
|---|---|
| Size | 31.5 MB |
| Tags | CPython 3.12 Linux glibc 2.28+ ARM64 |
|
SHA-256 checksum How to use checksums |
233e854cde02812003aec906f24e3b0f24791a7b8a4c1bfa39c5d8e76af58148
|
|
BLAKE2b-256 checksum How to use checksums |
f67b56cdc152c410ecec23b8fdb8df019cabee54a0bbde9148059d2429ed6afe
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / pyramids_gis-0.68.0-cp312-cp312-macosx_11_0_x86_64.whl
| Download URL | pyramids_gis-0.68.0-cp312-cp312-macosx_11_0_x86_64.whl |
|---|---|
| Size | 49.1 MB |
| Tags | CPython 3.12 macOS 11.0+ x86-64 |
|
SHA-256 checksum How to use checksums |
eea5dddde5f9038be89ec638599da4636966121a8a0a06ebf2839d47c6173982
|
|
BLAKE2b-256 checksum How to use checksums |
3400cbe38d87b5f874ebac5929da6b3dd01b1fe75dab83aefbba020368a4b3c7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / pyramids_gis-0.68.0-cp312-cp312-macosx_11_0_arm64.whl
| Download URL | pyramids_gis-0.68.0-cp312-cp312-macosx_11_0_arm64.whl |
|---|---|
| Size | 44.5 MB |
| Tags | CPython 3.12 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
fe12baf70b76bc730249d675e740b3a82c418b9752bcc119a6d55f530322a4f4
|
|
BLAKE2b-256 checksum How to use checksums |
d3b7d2be4f11e834f5d9dc2ce7fbc6a4a01b5f0f1da27e8ed6aae86fadbe7d2b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / pyramids_gis-0.68.0-cp311-cp311-win_amd64.whl
| Download URL | pyramids_gis-0.68.0-cp311-cp311-win_amd64.whl |
|---|---|
| Size | 51.6 MB |
| Tags | CPython 3.11 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
896b0800cd3fce55e0557f4231d4d2c05396da6addea07d47b13ada3d1708a9f
|
|
BLAKE2b-256 checksum How to use checksums |
091e506c8ced15a1f69390a53aeb1762b5c619738786688eb03fc7c25c216f00
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / pyramids_gis-0.68.0-cp311-cp311-musllinux_1_2_x86_64.whl
| Download URL | pyramids_gis-0.68.0-cp311-cp311-musllinux_1_2_x86_64.whl |
|---|---|
| Size | 41.4 MB |
| Tags | CPython 3.11 Linux musl 1.2+ x86-64 |
|
SHA-256 checksum How to use checksums |
69744c8236da64b32baa52366720a21500427d5340227dd324893b042e94f6a8
|
|
BLAKE2b-256 checksum How to use checksums |
59391c121e0bcc1e50e3aa2d44553d0ee5337f67f492dc44d09c8d80d3e9fcee
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / pyramids_gis-0.68.0-cp311-cp311-musllinux_1_2_aarch64.whl
| Download URL | pyramids_gis-0.68.0-cp311-cp311-musllinux_1_2_aarch64.whl |
|---|---|
| Size | 40.0 MB |
| Tags | CPython 3.11 Linux musl 1.2+ ARM64 |
|
SHA-256 checksum How to use checksums |
9222f8750bfd88beefc13b9efc64ad4254d907b0c993bacf6ad396c9b242c553
|
|
BLAKE2b-256 checksum How to use checksums |
331c7687f6468cb8076d998de0179019312bb5c53c481f25e36f41172805c635
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / pyramids_gis-0.68.0-cp311-cp311-manylinux_2_28_x86_64.whl
| Download URL | pyramids_gis-0.68.0-cp311-cp311-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 33.0 MB |
| Tags | CPython 3.11 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
673b748c7c841535ca5771768849761eae9222a80388e679b016a595a425aded
|
|
BLAKE2b-256 checksum How to use checksums |
31d6b380a026d3c1a1f04be5110ae355b658e20dc5346d06c8ac3db17eea1ad5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / pyramids_gis-0.68.0-cp311-cp311-manylinux_2_28_aarch64.whl
| Download URL | pyramids_gis-0.68.0-cp311-cp311-manylinux_2_28_aarch64.whl |
|---|---|
| Size | 31.5 MB |
| Tags | CPython 3.11 Linux glibc 2.28+ ARM64 |
|
SHA-256 checksum How to use checksums |
f2eb90f013042bbee6b957d3da507f76384549322b1760dfd32725cbd703b712
|
|
BLAKE2b-256 checksum How to use checksums |
7d3d14f4ec435d2ab855c02c17e0199e83d16efb2aee56b7483cbd60fef12c3b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / pyramids_gis-0.68.0-cp311-cp311-macosx_11_0_x86_64.whl
| Download URL | pyramids_gis-0.68.0-cp311-cp311-macosx_11_0_x86_64.whl |
|---|---|
| Size | 49.1 MB |
| Tags | CPython 3.11 macOS 11.0+ x86-64 |
|
SHA-256 checksum How to use checksums |
d8536ee24c8ad8ac9c76bbef93ec3635b697f2cf51e2ed87d75bd46a0b7420bf
|
|
BLAKE2b-256 checksum How to use checksums |
ceb875925be30d91b12172e36746b01427359fa4f9ceeb6a995dbe48c710cd2c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / pyramids_gis-0.68.0-cp311-cp311-macosx_11_0_arm64.whl
| Download URL | pyramids_gis-0.68.0-cp311-cp311-macosx_11_0_arm64.whl |
|---|---|
| Size | 44.5 MB |
| Tags | CPython 3.11 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
5067b39f573c7abfcdd3343b9481f4c63d3f6fa02267fa29b0ef6d6705874038
|
|
BLAKE2b-256 checksum How to use checksums |
254c9897d6a7d5c1128aeb9a891ae768a208b0fba923af7a0c4f817d94769594
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
