gdar-base 1.2.0.post2

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 — map projections (requires GDAL, see below)
• plotting — matplotlib
• interactive — IPython

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

GDAL dependency

GDAL is not required by gdar-base itself, but several downstream packages (notably gdar-crs) need it. Since geocoding depends on gdar-crs, many SAR processing workflows will need GDAL.

Packages that depend on GDAL (including gdar-base[crs]) require the system GDAL library to be installed separately.

Ubuntu

Installing GDAL

Make sure to install both gdal-bin and libgdal-dev packages.

MacOS

Install using Homebrew:

brew install gdal

Verifying the installation

After installing GDAL, you should be able to run ogrinfo --version from your shell and see output like GDAL 3.12.3 "Chicoutimi", released 2026/03/17 (debug build).

Installing the GDAL Python bindings

Pin the Python bindings to the matching system GDAL version:

uv pip install numpy setuptools
uv pip install --no-build-isolation "gdal==$(gdal-config --version)"

Both numpy and setuptools must be installed first because the GDAL Python bindings build requires them. The --no-build-isolation flag is needed because of this issue.

Development

Installing from the NORCE GitLab registry

Internal users and contributors can install pre-release versions from the NORCE GitLab package registry. Two token types are supported:

• opengdar deploy token: From the earth-observation/opengdar group page in GitLab, go to Settings → Repository → Deploy Tokens and create a token with the read_package_registry scope. Note the auto-assigned username (e.g. gitlab+deploy-token-42).
• Personal access token: Create a new access token in GitLab with the read_api scope. The username for personal tokens is __token__.

Installing with pip

pip install gdar-base \
    --index-url https://<username>:<token>@gitlab.norceresearch.no/api/v4/groups/523/-/packages/pypi/simple

Replace <username> and <token> with the credentials from the previous step (e.g. gitlab+deploy-token-48 and the token value, or __token__ and a personal access token).

Installing with uv

Add gdar-base to your project's dependency list and configure the index in pyproject.toml:

[tool.uv]
no-build-isolation-package = ["gdal"]

[[tool.uv.index]]
name = "opengdar"
url = "https://gitlab.norceresearch.no/api/v4/groups/523/-/packages/pypi/simple"
explicit = true

[tool.uv.sources]
gdar-base = { index = "opengdar" }

The index section tells uv where to find gdar packages. With explicit = true, only packages listed in [tool.uv.sources] are fetched from that index; everything else comes from PyPI.

Set the following environment variables to authenticate:

# bash / zsh — for deploy tokens:
export UV_INDEX_OPENGDAR_USERNAME="gitlab+deploy-token-NN"
export UV_INDEX_OPENGDAR_PASSWORD="<deploy_token>"

# or for personal access tokens:
export UV_INDEX_OPENGDAR_USERNAME="__token__"
export UV_INDEX_OPENGDAR_PASSWORD="<personal_token>"

Then sync your environment:

uv sync --extra crs --extra plotting --extra interactive

A sample-pyproject.toml with the full configuration is included in the repository.

Creating container images

The easiest way to build an image with gdar installed is to start from one with a sufficiently recent Python preinstalled, along with GDAL and its Python bindings.

One good source for base images is OSGeo/gdal on GitHub.

Dockerfile and pyproject.toml examples for building a custom image with GDAR are provided in this snippet.

Building behind the NORCE firewall (with NORCE SSL certs)

1. Place the Dockerfile and pyproject.toml files in the project root.
2. Export the SSL certs:

   security find-certificate -p -c 'Norwegian Research Centre Root CA' \
       /Library/Keychains/System.keychain > ca-certificates.crt
   

3. Build:

   docker build \
       --secret id=opengdar-token,env=UV_INDEX_OPENGDAR_PASSWORD \
       --secret id=ca-certificates,src=ca-certificates.crt \
       -t <tag> .
   

Building without extra certs

Remove lines 4-6 in Dockerfile to disable extra SSL certs, then:

docker build \
    --secret id=opengdar-token,env=UV_INDEX_OPENGDAR_PASSWORD \
    -t <tag> .

Internal links

• GDAR wiki — central documentation hub
• OpenGDAR API Reference — auto-generated from docstrings
• Release schedule

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.