dzsat 1.0.1

Geology-1 satellite data preprocessing algorithms

dzsat

dzsat is a Python toolkit for preprocessing Geology-1 (地质一号) 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) 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

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 or a pre-built wheel from Christoph Gohlke's repository.

---

Quick Start

Coregister all bands in a scene folder

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

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

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