Metadata-Version: 2.4
Name: dzsat
Version: 1.0.2
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 (地质一号)](https://www.cnsa.gov.cn/) satellite imagery, developed at China University of Geosciences (CUG). 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's repository](https://github.com/cgohlke/geospatial-wheels).

---

## Quick Start

### Coregister all bands in a scene folder

```python
from geology.geometry.registration import arosics_registration

arosics_registration(
    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 geology.geometry.registration import shift_info_calculate

shift_info_calculate(
    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
arosics_registration(
    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

### `arosics_registration`

```
arosics_registration(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 |

### `shift_info_calculate`

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/
├── geology/
│   ├── __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
