dzsat 1.0.8

Geology-1 satellite data preprocessing algorithms

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) 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.
• Configurable resampling — Supports nearest, bilinear, cubic, cubic_spline, and lanczos resampling algorithms for the warping step.
• Displacement vector field plots — Optionally saves per-band quiver plots showing tie-point shifts and statistics (enable with save_plot=True).
• 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 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

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

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=3,                # keep 1/9 of low-shift tie points
    resamp_alg='bilinear',        # resampling algorithm for warping
    save_plot=False,              # save displacement vector field plot
)

---

API Reference

coregister_folder

coregister_folder(folder_path, ref_band=9, grid_res=48, 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=3,
                  resamp_alg='bilinear', save_plot=False)

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	48	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	3	Thinning step size
resamp_alg	str	'bilinear'	Resampling algorithm ('nearest', 'bilinear', 'cubic', 'cubic_spline', 'lanczos')
save_plot	bool	False	Save displacement vector field plot

coregister_scene

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

Parameter	Type	Default	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
plot_dir	str	None	Directory for plots; defaults to coreg_plots/ beside out_path

---

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