Metadata-Version: 2.4
Name: gdar-base
Version: 1.2.2
Summary: GDAR -- The Generic Data Raster
Author-email: Geir Engen <geen@norceresearch.no>, Yngvar Larsen <ynla@norceresearch.no>, Tom Grydeland <tgry@norceresearch.no>, Heidi Hindberg <hehi@norceresearch.no>, Jakob Grahn <jgra@norceresearch.no>, Ingar Arntzen <inar@norceresearch.no>, Daniel Johansen Trosten <dtro@norceresearch.no>, Temesgen Gebrie Yitayew <teyi@norceresearch.no>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: InSAR,SAR,geospatial,raster,remote-sensing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.10
Requires-Dist: astropy
Requires-Dist: numpy
Requires-Dist: pyproj
Requires-Dist: python-dateutil
Requires-Dist: scipy
Requires-Dist: shapely
Provides-Extra: crs
Requires-Dist: gdal; extra == 'crs'
Requires-Dist: rasterio; extra == 'crs'
Provides-Extra: interactive
Requires-Dist: ipython; extra == 'interactive'
Provides-Extra: plotting
Requires-Dist: matplotlib; extra == 'plotting'
Description-Content-Type: text/markdown

# GDAR - The Generic Data Raster

## What is GDAR?

GDAR — the **G**eneric **D**ata **R**aster — 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
`DataRaster`s 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](https://www.norceresearch.no/) and used in
production SAR/InSAR processing chains, including
[InSAR Norge](https://insar.ngu.no/), 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:

```bash
pip install gdar-base
```

or with [uv](https://docs.astral.sh/uv/):

```bash
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](#installing-the-crs-extra)
  below.
- `plotting` — matplotlib
- `interactive` — IPython

```bash
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)](#using-uv-or-pip)** — install the system GDAL
  library via your OS package manager, then pin the Python binding
  to that version.
- **[Using conda](#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](https://mothergeo-py.readthedocs.io/en/latest/development/how-to/gdal-ubuntu-pkg.html)
— install both `gdal-bin` and `libgdal-dev`.

##### MacOS

```bash
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:

```bash
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:

```bash
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:

```bash
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](./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.

