gdar-base 1.2.2

GDAR -- The Generic Data Raster

GDAR - The Generic Data Raster

What is GDAR?

GDAR — the Generic Data Raster — is a Python library for working with gridded geospatial data. Its central abstraction is the DataRaster, which combines a data source with metadata describing the grid the data lives on (shape, origin, sample spacing, coordinate reference system) and the meaning of its values (data type, nodata sentinel, units). The data source can be a NumPy-like array already in memory, a file read on demand, or a get_data() callable that computes the necessary subset of the data when invoked. That last option gives DataRaster pull semantics: an entire processing chain can be assembled in which intermediate steps are neither written to disk nor ever materialised in their entirety — data is produced only for the regions that downstream consumers actually request. Once data is wrapped in a DataRaster, operations that would otherwise require juggling separate geotransforms, masks, and projection strings — indexing by physical coordinates, resampling onto another grid, cropping, reading and writing native file formats — become straightforward method calls that keep the spatial bookkeeping in sync with the pixel data.

A companion abstraction, the Collection, groups multiple related DataRasters that belong together — for example time slices of a dataset, bands from a multispectral instrument, or polarimetric channels from a SAR acquisition.

gdar-base is the core of the library and has deliberately few dependencies: NumPy, with optional extras for plotting (matplotlib) and map-projection support. It forms the foundation for a family of companion packages that build on the same DataRaster abstraction:

• gdar-crs — coordinate reference systems and map projections
• gdar-orbit — satellite orbit propagation and geometry
• gdar-sar — synthetic-aperture radar processing primitives
• gdar-optical — remotely-sensed optical data
• gafa — geometry- and frequency-agnostic SAR focusing and simulation

GDAR is developed at NORCE and used in production SAR/InSAR processing chains, including InSAR Norge, Norway's national ground-deformation monitoring service developed by NORCE based on GDAR and its precursor GSAR. The core raster machinery is domain-agnostic, however, and equally applicable to any gridded dataset — elevation models, classification maps, time-series stacks, and so on.

Installation

Install from PyPI:

pip install gdar-base

or with uv:

uv pip install gdar-base

Optional extras:

• crs — coordinate reference systems and geocoding. Pulls in rasterio; also requires system GDAL and a matching Python binding. See Installing the crs extra below.
• plotting — matplotlib
• interactive — IPython

pip install "gdar-base[plotting,interactive]"

Installing the crs extra

The Python gdal package is unusual: each release builds against a specific version of the system GDAL library, and the two must match at runtime. The crs extra declares gdal as a dependency without a version pin, because the right pin depends on whichever libgdal happens to be installed on the host — left to resolve on its own, gdal will pick the newest PyPI release and the build will fail if that's newer than your system libgdal. You pin it explicitly to your system version as part of the install.

Two reasonable ways to do this:

• Using uv (or pip) — install the system GDAL library via your OS package manager, then pin the Python binding to that version.
• Using conda — install GDAL (system library and Python binding together) from conda-forge. Conda manages both halves coherently; no pin needed.

Using uv (or pip)

1. Install the system GDAL library

Ubuntu

Installing GDAL — install both gdal-bin and libgdal-dev.

MacOS

brew install gdal

Verifying

ogrinfo --version should now print something like GDAL 3.12.3 "Chicoutimi", released 2026/03/17.

2. Pin and install the Python binding

In a project that depends on gdar-base[crs], pin gdal to your system version and sync:

uv add "gdal==$(gdal-config --version)"
uv sync

uv builds the binding from the PyPI sdist against your system libgdal during install. The pin lands in your project's pyproject.toml and uv.lock, so subsequent uv sync runs preserve the install.

For a venv without a project pyproject.toml, use uv pip (or pip) directly:

uv pip install "gdal==$(gdal-config --version)"
uv pip install "gdar-base[crs]"

Using conda

conda-forge packages GDAL with its Python bindings together: the system library and Python module are version-locked and update atomically. No manual version pin required.

Create an environment with GDAL, then install gdar-base[crs] into it:

conda create -n gdar-env python=3.12 -c conda-forge gdal
conda activate gdar-env
pip install "gdar-base[crs]"

mamba is a much faster drop-in replacement for conda — use mamba create … / mamba install … in place of the conda invocations above if you have it.

gdar-base itself is published only on PyPI, so the final step is pip install regardless of how the environment is created.

License

This project is licensed under the Apache License, Version 2.0. You may obtain a copy of the license at https://www.apache.org/licenses/LICENSE-2.0 or in the LICENSE file distributed with this source.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.