Metadata-Version: 2.4
Name: gdar-sar
Version: 1.2.2
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 Gebrie 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
Requires-Dist: xmltodict
Provides-Extra: crs
Requires-Dist: gdar-base[crs]; 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.  See
[`gdar-base`](https://pypi.org/project/gdar-base/) for the foundation
package and an introduction to the `DataRaster` abstraction; requires
[`gdar-orbit`](https://pypi.org/project/gdar-orbit/) for orbit
propagation.

## 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` — coordinate reference systems and geocoding.  Pulls in
  `gdar-base[crs]`, which in turn requires system GDAL and a matching
  Python binding.  See the
  [`gdar-base` README](https://pypi.org/project/gdar-base/) for the
  GDAL installation procedure.
- `plotting` — matplotlib
- `interactive` — IPython

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

For conda environments and other topics shared across the OpenGDAR
packages, see the [`gdar-base` README](https://pypi.org/project/gdar-base/).

## Testing

```bash
pytest tests/
```

Tests in `test_simplecrs.py` are skipped automatically if `rasterio` is
not installed (i.e. when the `crs` extra has not been set up).

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

