Metadata-Version: 2.4
Name: gdar-base
Version: 1.2.0.post2
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: fiona
Requires-Dist: h5py
Requires-Dist: numpy
Requires-Dist: pyproj
Requires-Dist: python-dateutil
Requires-Dist: scipy
Requires-Dist: shapely
Requires-Dist: simplekml
Requires-Dist: xarray
Requires-Dist: xmltodict
Provides-Extra: crs
Requires-Dist: gdal>=3.5; 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` — map projections (requires GDAL, see below)
- `plotting` — matplotlib
- `interactive` — IPython

```bash
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](https://mothergeo-py.readthedocs.io/en/latest/development/how-to/gdal-ubuntu-pkg.html)

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

#### MacOS

Install using Homebrew:

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

```bash
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](https://github.com/astral-sh/uv/issues/2252).

## 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`

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

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

```bash
uv sync --extra crs --extra plotting --extra interactive
```

A [`sample-pyproject.toml`](./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](https://github.com/OSGeo/gdal/tree/master/docker).

`Dockerfile` and `pyproject.toml` examples for building a custom image
with GDAR are provided in
[this snippet](https://gitlab.norceresearch.no/earth-observation/opengdar/gdar-base/-/snippets/33).

#### Building behind the NORCE firewall (with NORCE SSL certs)

1. Place the `Dockerfile` and `pyproject.toml` files in the project
   root.
1. Export the SSL certs:
    ```bash
    security find-certificate -p -c 'Norwegian Research Centre Root CA' \
        /Library/Keychains/System.keychain > ca-certificates.crt
    ```
1. Build:
    ```bash
    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:

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

### Internal links

- [GDAR wiki](https://gitlab.norceresearch.no/earth-observation/wiki/-/wikis/0_home) — central documentation hub
- [OpenGDAR API Reference](https://earth-observation.pages.norce.dev/opengdar/docs/opengdar) — auto-generated from docstrings
- [Release schedule](https://gitlab.norceresearch.no/earth-observation/wiki/-/wikis/Deployment-&-Maintenance/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](./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.

