Metadata-Version: 2.4
Name: gdar-sar
Version: 1.2.0.post3
Summary: GDAR-SAR -- Synthetic aperture radar geometry and functionality for GDAR
Author-email: Geir Engen <geen@norceresearch.no>, Yngvar Larsen <ynla@norceresearch.no>, Tom Grydeland <tgry@norceresearch.no>, Temesgen Gabrie Yitayew <teyi@norceresearch.no>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: InSAR,SAR,geospatial,raster,remote-sensing,synthetic-aperture-radar
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: gdar-base>=1.2.0
Requires-Dist: gdar-orbit>=1.2.0
Requires-Dist: tifffile
Provides-Extra: crs
Requires-Dist: gdar-base[crs]; extra == 'crs'
Requires-Dist: rasterio; extra == 'crs'
Provides-Extra: interactive
Requires-Dist: gdar-base[interactive]; extra == 'interactive'
Requires-Dist: ipython; extra == 'interactive'
Provides-Extra: plotting
Requires-Dist: gdar-base[plotting]; extra == 'plotting'
Requires-Dist: matplotlib; extra == 'plotting'
Description-Content-Type: text/markdown

# gdar-sar

Synthetic aperture radar geometry and functionality for the GDAR
processing framework.  Part of the OpenGDAR family of packages.
Requires `gdar-base` and `gdar-orbit`.

## Type registration

`gdar.sar.meta` and `gdar.sar.refsys` define subtypes of
`gdar.base.Meta` and `gdar.base.Meta_refsys` that must be registered
before they can be instantiated.  Registration happens automatically
when you `import gdar.sar`, so make sure this import occurs in your
Python context **before** creating any SAR `Meta` or `Meta_refsys`
objects.  When reading files with `read_gdr()`, the reader handles
this for you.

## Modules

### `gdar.sar.meta` -- SAR metadata

SAR-specific metadata extending the base `Meta` class:

- **`Meta_sar`** -- metadata container for SAR rasters (Doppler
  centroid, pulse repetition frequency, chirp parameters, etc.).
- `create_doppler_grid()` -- generate a grid of Doppler centroid
  values across the raster.

### `gdar.sar.refsys` -- Reference systems

SAR coordinate reference system definitions used by `DataRaster`
geometry methods:

- **`Meta_refsys_mssar_zd_sr`** -- monostatic SAR, zero-Doppler,
  slant-range reference system.
- **`Meta_refsys_mssar_zd_gr`** -- monostatic SAR, zero-Doppler,
  ground-range reference system.
- **`Meta_refsys_bssar_bmcd_sr`** -- bistatic SAR, beam-centre
  Doppler, slant-range reference system.

### `gdar.sar.bistatic_geometry` -- Bistatic SAR geometry

Geometry routines for bistatic (e.g. TanDEM-X) configurations:

- **`BistaticGeometry`** -- class encapsulating transmitter/receiver
  orbits and the bistatic range equation.
- `bistatic_from_meta()` -- construct a `BistaticGeometry` from raster
  metadata.
- `bistatic_geod_from_coord()` -- convert SAR coordinates to geodetic.
- `bistatic_xyz2sar()` -- convert Cartesian XYZ to SAR coordinates.
- `brange_from_azel()` -- compute bistatic range from azimuth and
  elevation.

### `gdar.sar.rastertools` -- Raster processing utilities

Higher-level functions operating on SAR `DataRaster` objects:

- **`back_geocode_dem()`** / **`back_geocode_raster()`** --
  back-geocode a DEM or raster using SAR geometry.
- **`grd_merger()`** -- merge multiple GRD products into one raster.
- `band_split_pixels()` / `band_split_parameters()` -- spectral band
  splitting for split-spectrum InSAR.
- `azimuth_splitter()` / `range_splitter()` -- split an SLC in
  azimuth or range.
- `slc_processing_meta()` -- build metadata for SLC processing steps.
- `update_trajectory()` -- replace a raster's trajectory with a
  precision orbit.
- `is_descending()` -- check whether the orbit pass is descending.

### `gdar.sar.metatools` -- Metadata helpers

- `update_bmeta_with_brefsys()` -- update bistatic metadata with a
  beam-centre reference system.

## Installation

Install from PyPI:

```bash
pip install gdar-sar
```

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

```bash
uv pip install gdar-sar
```

Dependencies (including `gdar-base` and `gdar-orbit`) are installed
automatically.

Optional extras:

- `crs` — map projections and geocoding (requires GDAL; see the
  `gdar-base` README for GDAL installation instructions)
- `plotting` — matplotlib
- `interactive` — IPython

```bash
pip install "gdar-sar[crs,plotting]"
```

## Testing

```bash
pytest tests/
```

## Development

### Installing from the NORCE GitLab registry

Internal users and contributors can install pre-release versions from
the NORCE GitLab package registry.  Authenticate with either a
**deploy token** or a **personal access token**:

- **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.  The
  username is the auto-assigned name shown when the token is created
  (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__`.

Set the following environment variables:

```bash
# bash / zsh
export UV_INDEX_OPENGDAR_USERNAME=<username>
export UV_INDEX_OPENGDAR_PASSWORD=<token>
```

Then build the environment:

```bash
uv venv --python 3.12
uv sync
```

If you need GDAL/CRS support, install the GDAL build prerequisites
first (see the `gdar-base` README), then:

```bash
uv pip install numpy setuptools
uv pip install --no-build-isolation "gdal==$(gdal-config --version)"
uv sync --extra crs
```

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

