Metadata-Version: 2.4
Name: dzsat
Version: 1.0.7
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` using **cascading (chain) registration**: bands are processed in two passes from the reference band toward shorter and longer wavelengths respectively. Each step uses the previous step's registered output as the new reference, exploiting the higher spectral similarity between adjacent bands for more robust NCC matching. The reference band is copied directly to the output. 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
