Metadata-Version: 2.4
Name: dzsat
Version: 1.0.3
Summary: Geology-1 satellite data preprocessing algorithms
Author-email: HaixuHe <20161001925@cug.edu.cn>
License-Expression: MIT
Keywords: Geology-1,satellite,remote sensing
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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 :: Software Development :: Libraries
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# dzsat

**dzsat** is a Python toolkit for preprocessing Geology-1 satellite imagery, developed at China University of Geosciences. The library focuses on geometric correction and band-to-band coregistration, with plans to expand to radiometric calibration and other preprocessing workflows.

---

## Features

- **Band-to-band coregistration** — Local cross-correlation coregistration (via [arosics](https://github.com/GFZ/arosics)) across all 16 spectral bands of Geology-1 Level-3 products.
- **Sobel gradient preprocessing** — Eliminates spectral contrast-reversal artifacts between VNIR bands before NCC matching.
- **Bad-data masking** — Automatically excludes zero-fill and nodata regions from tie-point computation.
- **Tie-point thinning** — Spatially thins low-displacement tie points to accelerate DESHIFTER interpolation without sacrificing accuracy.
- **Fully parameterised** — All matching parameters (grid resolution, window size, max shift, reliability threshold, etc.) are exposed as function arguments.

---

## Installation

```bash
pip install dzsat
```

### Dependencies

| Package      | Purpose                      |
| ------------ | ---------------------------- |
| `numpy`    | Array operations             |
| `GDAL`     | Geospatial raster I/O        |
| `rasterio` | GeoTIFF read/write           |
| `scipy`    | Sobel gradient computation   |
| `arosics`  | Local coregistration engine  |
| `geoarray` | Geo-referenced array wrapper |
| `Pillow`   | Image utilities              |

> **Note:** GDAL must be installed before `pip install dzsat`. On Windows it is recommended to install GDAL via [OSGeo4W](https://trac.osgeo.org/osgeo4w/) or a pre-built wheel from [Christoph Gohlke&#39;s repository](https://github.com/cgohlke/geospatial-wheels).

---

## Quick Start

### Coregister all bands in a scene folder

```python
from dzsat.geometry.registration import coregister_folder

coregister_folder(
    folder_path=r"D:\data\DZ01V_L3_E30.2_S25.9_20260211_01_T1",
    ref_band=9,          # reference band (default: B9)
)
```

Output is written to `folder_path + "_registration"`.

### Coregister a single band pair

```python
from dzsat.geometry.registration import coregister_scene

coregister_scene(
    ref_path=r"D:\data\scene\B9.TIF",
    warp_path=r"D:\data\scene\B7.TIF",
    out_path=r"D:\data\output\B7_coreg.TIF",
)
```

### Advanced — custom parameters

```python
coregister_folder(
    folder_path=r"D:\data\scene",
    ref_band=9,
    grid_res=64,                  # coarser grid → faster
    window_size=(80, 80),         # smaller matching window
    max_shift=50,                 # allow larger displacements
    min_reliability=70,           # stricter NCC quality filter
    preprocess_gradient=True,     # Sobel preprocessing (recommended)
    thin_low_shift=True,          # thin tie points in low-shift areas
    thin_shift_threshold_m=28.0,  # threshold ≈ 2 px at 14 m GSD
    thin_factor=2,                # keep 1/4 of low-shift tie points
)
```

---

## API Reference

### `coregister_folder`

```
coregister_folder(folder_path, ref_band=9, grid_res=32, window_size=(120,120),
                  max_shift=30, min_reliability=60, tieP_filter_level=2,
                  preprocess_gradient=True, thin_low_shift=True,
                  thin_shift_threshold_m=28.0, thin_factor=2)
```

Coregisters all 16 bands in `folder_path` against the reference band. Results are saved to `folder_path + "_registration"`.

| Parameter                  | Type      | Default       | Description                              |
| -------------------------- | --------- | ------------- | ---------------------------------------- |
| `folder_path`            | `str`   | —            | Directory containing `*B<n>.TIF` files |
| `ref_band`               | `int`   | `9`         | Reference band number (1–16)            |
| `grid_res`               | `int`   | `32`        | Tie-point grid spacing in pixels         |
| `window_size`            | `tuple` | `(120,120)` | NCC matching window in pixels            |
| `max_shift`              | `int`   | `30`        | Maximum allowed shift in pixels          |
| `min_reliability`        | `float` | `60`        | Minimum NCC reliability (0–100)         |
| `tieP_filter_level`      | `int`   | `2`         | Tie-point filter level (0–3)            |
| `preprocess_gradient`    | `bool`  | `True`      | Use Sobel gradient images for matching   |
| `thin_low_shift`         | `bool`  | `True`      | Thin tie points in low-shift regions     |
| `thin_shift_threshold_m` | `float` | `28.0`      | Displacement threshold for thinning (m)  |
| `thin_factor`            | `int`   | `2`         | Thinning step size                       |

### `coregister_scene`

Same parameters as above (excluding `folder_path` / `ref_band`), plus:

| Parameter     | Type    | Description                           |
| ------------- | ------- | ------------------------------------- |
| `ref_path`  | `str` | Path to the reference GeoTIFF         |
| `warp_path` | `str` | Path to the target GeoTIFF            |
| `out_path`  | `str` | Output path for the corrected GeoTIFF |

---

## Project Structure

```
dzsat/
├── dzsat/
│   ├── __init__.py
│   └── geometry/
│       ├── __init__.py
│       └── registration.py   # coregistration algorithms
├── pyproject.toml
└── README.md
```

---

## Roadmap

- [ ] Radiometric calibration (DN → Radiance → Reflectance)
- [ ] Atmospheric correction
- [ ] Orthorectification
- [ ] Cloud / shadow masking
- [ ] Multi-scene mosaicking

---

## License

MIT © HaixuHe, China University of Geosciences
