| 1 |
""" |
| 2 |
This code is part of the Python PolSARpro software: |
| 3 |
|
| 4 |
"A re-implementation of selected PolSARPro functions in Python, |
| 5 |
following the scientific recommendations of PolInSAR 2021" |
| 6 |
|
| 7 |
developed within an ESA funded project with SATIM. |
| 8 |
|
| 9 |
Author: Olivier D'Hondt, 2025. |
| 10 |
Scientific advisors: Armando Marino and Eric Pottier. |
| 11 |
|
| 12 |
Licensed under the Apache License, Version 2.0 (the "License"); |
| 13 |
you may not use this file except in compliance with the License. |
| 14 |
You may obtain a copy of the License at |
| 15 |
|
| 16 |
http://www.apache.org/licenses/LICENSE-2.0 |
| 17 |
|
| 18 |
Unless required by applicable law or agreed to in writing, software |
| 19 |
distributed under the License is distributed on an "AS IS" BASIS, |
| 20 |
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 21 |
See the License for the specific language governing permissions and |
| 22 |
limitations under the License. |
| 23 |
|
| 24 |
----- |
| 25 |
|
| 26 |
# Description: module containing speckle filtering functions |
| 27 |
|
| 28 |
""" |
| 29 |
|
| 30 |
import dask.array as da |
| 31 |
import numpy as np |
| 32 |
import xarray as xr |
| 33 |
from scipy.ndimage import convolve |
| 34 |
|
| 35 |
from polsarpro.auxil import validate_dataset |
| 36 |
from polsarpro.util import S_to_C3, _boxcar_core, boxcar |
| 37 |
|
| 38 |
|
| 39 |
def pwf( |
| 40 |
input_data: xr.Dataset, |
| 41 |
train_window_size: list[int, int] = [9, 9], |
| 42 |
test_window_size: list[int, int] = [1, 1], |
| 43 |
) -> xr.Dataset: |
| 44 |
""" |
| 45 |
Speckle reduction using Polarimetric Whitening Filter. |
| 46 |
|
| 47 |
Args: |
| 48 |
input_data (xr.Dataset): Input polarimetric SAR dataset. Supported types are: |
| 49 |
|
| 50 |
- "S": Sinclair scattering matrix |
| 51 |
|
| 52 |
- "C3": Lexicographic covariance matrix |
| 53 |
|
| 54 |
- "T3": Pauli coherency matrix |
| 55 |
|
| 56 |
- "C4" and "T4": 4x4 versions of the above |
| 57 |
|
| 58 |
- "C2": Dual-polarimetric covariance |
| 59 |
train_window_size (list[int, int], optional): Size of the spatial averaging window to be applied to compute the inverse covariance (boxcar filter). Defaults to [9, 9]. |
| 60 |
test_window_size (list[int, int], optional): Size of the spatial averaging window to be applied on the input covariance (boxcar filter). Defaults to [1, 1]. |
| 61 |
|
| 62 |
Returns: |
| 63 |
xr.Dataset: Result of the filtering. |
| 64 |
|
| 65 |
Notes: |
| 66 |
If the S matrix is given as an input, it will be converted to C3. |
| 67 |
""" |
| 68 |
|
| 69 |
allowed_poltypes = ("S", "C2", "C3", "C4", "T3", "T4") |
| 70 |
poltype = validate_dataset(input_data, allowed_poltypes=allowed_poltypes) |
| 71 |
|
| 72 |
if ( |
| 73 |
test_window_size[0] >= train_window_size[0] |
| 74 |
or test_window_size[1] >= train_window_size[1] |
| 75 |
): |
| 76 |
raise ValueError( |
| 77 |
"Testing window size must be smaller than training window size." |
| 78 |
) |
| 79 |
|
| 80 |
if poltype in ["C2", "C3", "T3", "C4", "T4"]: |
| 81 |
in_ = input_data |
| 82 |
elif poltype == "S": |
| 83 |
in_ = S_to_C3(input_data) |
| 84 |
else: |
| 85 |
raise ValueError(f"Invalid polarimetric type: {input_data.poltype}") |
| 86 |
|
| 87 |
new_dims = tuple(input_data.dims) |
| 88 |
|
| 89 |
eps = 1e-30 |
| 90 |
# pre-processing step, it is recommended to filter the matrices to mitigate speckle effects |
| 91 |
box_train = boxcar(in_, dim_az=train_window_size[0], dim_rg=train_window_size[1]) |
| 92 |
box_test = boxcar(in_, dim_az=test_window_size[0], dim_rg=test_window_size[1]) |
| 93 |
|
| 94 |
# remove NaNs to avoid errors in eigh |
| 95 |
mask = box_train.to_array().isnull().any("variable") |
| 96 |
# box_train = box_train.fillna(eps) |
| 97 |
|
| 98 |
M_box = _reconstruct_matrix_from_ds(box_train).data |
| 99 |
|
| 100 |
# Add tiny diagonal loading as a minimal safeguard against singular inversions. |
| 101 |
n = M_box.shape[-1] |
| 102 |
eye = da.eye(n) |
| 103 |
M_box = M_box + eps * eye |
| 104 |
|
| 105 |
# M = _reconstruct_matrix_from_ds(in_).data |
| 106 |
M = _reconstruct_matrix_from_ds(box_test).data |
| 107 |
# eigendecomposition |
| 108 |
meta = (np.array([], dtype="complex64").reshape((0, 0, 0, 0)),) |
| 109 |
M_inv = da.apply_gufunc(np.linalg.inv, "(i,j)->(i,j)", M_box, meta=meta) |
| 110 |
prod = np.matmul(M_inv, M) |
| 111 |
trace = np.trace(prod, axis1=2, axis2=3).real |
| 112 |
|
| 113 |
out = {"pwf": trace} |
| 114 |
# return trace |
| 115 |
|
| 116 |
return xr.Dataset( |
| 117 |
# add dimension names, account for 2D and 3D outputs |
| 118 |
{ |
| 119 |
k: (new_dims, v) if v.ndim == 2 else (new_dims + ("i",), v) |
| 120 |
for k, v in out.items() |
| 121 |
}, |
| 122 |
attrs=dict( |
| 123 |
poltype="pwf", |
| 124 |
description="Results of the PWF (Polarimetric Whitening Filter) speckle reduction method.", |
| 125 |
), |
| 126 |
coords=input_data.coords, |
| 127 |
).where(~mask) |
| 128 |
|
| 129 |
|
| 130 |
def refined_lee( |
| 131 |
input_data: xr.Dataset, window_size: int = 7, num_looks: int = 1 |
| 132 |
) -> xr.Dataset: |
| 133 |
""" |
| 134 |
Apply the Refined Lee Speckle Filter to a PolSAR dataset. |
| 135 |
|
| 136 |
Args: |
| 137 |
input_data (xr.Dataset): Input PolSAR dataset containing covariance or coherency matrices. Works for 2x2, 3x3 and 4x4 matrices. |
| 138 |
window_size (int, optional): Size of the filtering window (default is 7). |
| 139 |
num_looks (int or float, optional): Number of looks of the input data (default is 1). |
| 140 |
|
| 141 |
Returns: |
| 142 |
xr.Dataset: Speckle filtered PolSAR dataset. |
| 143 |
|
| 144 |
References: |
| 145 |
Lee, J.-S., Grunes, M. R., & Kwok, R. (1999). "Polarimetric SAR Speckle Filtering and Its Implications for Classification." IEEE Transactions on Geoscience and Remote Sensing, 37(5), 2363-2373. doi:10.1109/36.789467 |
| 146 |
""" |
| 147 |
# Validate input dataset |
| 148 |
allowed_poltypes = ("C2", "C3", "C4", "T3", "T4") |
| 149 |
poltype = validate_dataset(input_data, allowed_poltypes=allowed_poltypes) |
| 150 |
|
| 151 |
# test that num_looks is a number > 0 |
| 152 |
if num_looks <= 0 or not isinstance(num_looks, (int, float)): |
| 153 |
raise ValueError("num_looks must be a positive number") |
| 154 |
|
| 155 |
span = _compute_span(input_data) |
| 156 |
|
| 157 |
# use a different window size for gradient computation |
| 158 |
# also return an offset for efficient dilated convolutions |
| 159 |
nwg, off = _get_window_params(window_size) |
| 160 |
|
| 161 |
# smooth power image prior to gradient computation |
| 162 |
process_args = dict(dim_az=nwg, dim_rg=nwg, depth=(nwg, nwg)) |
| 163 |
span_smooth = da.map_overlap( # convolutions require overlapping chunks |
| 164 |
_boxcar_core, # used instead of boxcar() to avoid extra conversions |
| 165 |
span, |
| 166 |
**process_args, |
| 167 |
dtype="float32", |
| 168 |
) |
| 169 |
|
| 170 |
# directional gradient-based mask selection |
| 171 |
process_args = dict(off=off, depth=(off, off)) |
| 172 |
mask_index = da.map_overlap( # operation requires overlapping chunks |
| 173 |
_compute_mask_index, |
| 174 |
span_smooth, |
| 175 |
**process_args, |
| 176 |
dtype="int64", |
| 177 |
) |
| 178 |
|
| 179 |
# filter coefficient computation |
| 180 |
process_args = dict( |
| 181 |
window_size=window_size, num_looks=num_looks, depth=(window_size, window_size) |
| 182 |
) |
| 183 |
coeff = da.map_overlap( # convolutions require overlapping chunks |
| 184 |
_compute_reflee_coefficients, |
| 185 |
span, |
| 186 |
mask_index, |
| 187 |
**process_args, |
| 188 |
dtype="float32", |
| 189 |
) |
| 190 |
|
| 191 |
# apply filter to input matrix elements |
| 192 |
process_args = dict(window_size=window_size, depth=(window_size, window_size)) |
| 193 |
out = {} |
| 194 |
for var in input_data.data_vars: |
| 195 |
img = input_data[var].data |
| 196 |
filtered_img = da.map_overlap( # convolutions require overlapping chunks |
| 197 |
_apply_reflee_filter, |
| 198 |
img, |
| 199 |
coeff, |
| 200 |
mask_index, |
| 201 |
**process_args, |
| 202 |
dtype=img.dtype, |
| 203 |
) |
| 204 |
out[var] = filtered_img |
| 205 |
|
| 206 |
return xr.Dataset( |
| 207 |
# add dimension names |
| 208 |
{k: (tuple(input_data.dims), v) for k, v in out.items()}, |
| 209 |
attrs=dict( |
| 210 |
poltype=poltype, |
| 211 |
description=input_data.description, |
| 212 |
), |
| 213 |
coords=input_data.coords, |
| 214 |
) |
| 215 |
|
| 216 |
|
| 217 |
# below this line, functions are not meant to be called directly |
| 218 |
|
| 219 |
|
| 220 |
# this is a convenience function to give eigh the right data format |
| 221 |
def _reconstruct_matrix_from_ds(ds): |
| 222 |
|
| 223 |
eps = 1e-30 |
| 224 |
|
| 225 |
if {"y", "x"}.issubset(ds.dims): |
| 226 |
new_dims = ("y", "x") |
| 227 |
elif {"lat", "lon"}.issubset(ds.dims): |
| 228 |
new_dims = ("lat", "lon") |
| 229 |
else: |
| 230 |
ValueError( |
| 231 |
"Input data does not have valid dimension names. ('y', 'x') or ('lat', 'lon') allowed." |
| 232 |
) |
| 233 |
|
| 234 |
new_dims_array = new_dims + ("i", "j") |
| 235 |
if ds.poltype == "C2": |
| 236 |
# build each line of the T3 matrix |
| 237 |
M2_l1 = xr.concat((ds.m11, ds.m12), dim="j") |
| 238 |
M2_l2 = xr.concat((ds.m12.conj(), ds.m22), dim="j") |
| 239 |
|
| 240 |
# Concatenate all lines into a 2x2 matrix |
| 241 |
return ( |
| 242 |
xr.concat((M2_l1, M2_l2), dim="i") |
| 243 |
.transpose(*new_dims_array) |
| 244 |
.chunk({new_dims[0]: "auto", new_dims[1]: "auto", "i": 2, "j": 2}) |
| 245 |
+ eps |
| 246 |
) |
| 247 |
if ds.poltype in ["T3", "C3"]: |
| 248 |
# build each line of the T3 matrix |
| 249 |
M3_l1 = xr.concat((ds.m11, ds.m12, ds.m13), dim="j") |
| 250 |
M3_l2 = xr.concat((ds.m12.conj(), ds.m22, ds.m23), dim="j") |
| 251 |
M3_l3 = xr.concat((ds.m13.conj(), ds.m23.conj(), ds.m33), dim="j") |
| 252 |
|
| 253 |
# Concatenate all lines into a 3x3 matrix |
| 254 |
return ( |
| 255 |
xr.concat((M3_l1, M3_l2, M3_l3), dim="i") |
| 256 |
.transpose(*new_dims_array) |
| 257 |
.chunk({new_dims[0]: "auto", new_dims[1]: "auto", "i": 3, "j": 3}) |
| 258 |
+ eps |
| 259 |
) |
| 260 |
elif ds.poltype in ["T4", "C4"]: |
| 261 |
# build each line of the T4 matrix |
| 262 |
M4_l1 = xr.concat((ds.m11, ds.m12, ds.m13, ds.m14), dim="j") |
| 263 |
M4_l2 = xr.concat((ds.m12.conj(), ds.m22, ds.m23, ds.m24), dim="j") |
| 264 |
M4_l3 = xr.concat((ds.m13.conj(), ds.m23.conj(), ds.m33, ds.m34), dim="j") |
| 265 |
M4_l4 = xr.concat( |
| 266 |
(ds.m14.conj(), ds.m24.conj(), ds.m34.conj(), ds.m44), dim="j" |
| 267 |
) |
| 268 |
|
| 269 |
# concatenate all lines into a 4x4 matrix |
| 270 |
return ( |
| 271 |
xr.concat((M4_l1, M4_l2, M4_l3, M4_l4), dim="i") |
| 272 |
.transpose(*new_dims_array) |
| 273 |
.chunk({new_dims[0]: "auto", new_dims[1]: "auto", "i": 4, "j": 4}) |
| 274 |
+ eps |
| 275 |
) |
| 276 |
else: |
| 277 |
raise NotImplementedError( |
| 278 |
"Implemented only for C2, C3, T3 and C4 and T4 poltypes." |
| 279 |
) |
| 280 |
|
| 281 |
|
| 282 |
def _compute_mask_index(span: np.array, off: int) -> np.array: |
| 283 |
mask_index = np.zeros_like(span, dtype=da.uint8) |
| 284 |
|
| 285 |
# use a short name for more compact expressions |
| 286 |
I = np.pad(span, off, mode="reflect") |
| 287 |
|
| 288 |
# directional gradients on dilated 3x3 windows |
| 289 |
d0 = ( |
| 290 |
-I[: -2 * off, : -2 * off] |
| 291 |
+ I[: -2 * off, 2 * off :] |
| 292 |
- I[off:-off, : -2 * off] |
| 293 |
+ I[off:-off, 2 * off :] |
| 294 |
- I[2 * off :, : -2 * off] |
| 295 |
+ I[2 * off :, 2 * off :] |
| 296 |
) |
| 297 |
|
| 298 |
d1 = ( |
| 299 |
I[: -2 * off, off:-off] |
| 300 |
+ I[: -2 * off, 2 * off :] |
| 301 |
- I[off:-off, : -2 * off] |
| 302 |
+ I[off:-off, 2 * off :] |
| 303 |
- I[2 * off :, : -2 * off] |
| 304 |
- I[2 * off :, off:-off] |
| 305 |
) |
| 306 |
|
| 307 |
d2 = ( |
| 308 |
I[: -2 * off, : -2 * off] |
| 309 |
+ I[: -2 * off, off:-off] |
| 310 |
+ I[: -2 * off, 2 * off :] |
| 311 |
- I[2 * off :, : -2 * off] |
| 312 |
- I[2 * off :, off:-off] |
| 313 |
- I[2 * off :, 2 * off :] |
| 314 |
) |
| 315 |
|
| 316 |
d3 = ( |
| 317 |
I[: -2 * off, : -2 * off] |
| 318 |
+ I[: -2 * off, off:-off] |
| 319 |
+ I[off:-off, : -2 * off] |
| 320 |
- I[off:-off, 2 * off :] |
| 321 |
- I[2 * off :, off:-off] |
| 322 |
- I[2 * off :, 2 * off :] |
| 323 |
) |
| 324 |
|
| 325 |
# find index of maximum gradient |
| 326 |
dist = np.stack([d0, d1, d2, d3], axis=0) |
| 327 |
mask_index = np.argmax(np.abs(dist), axis=0) |
| 328 |
|
| 329 |
# determine the sign of the gradient for proper mask selection |
| 330 |
sign = _extract_value_at_indices(dist, mask_index) < 0 |
| 331 |
mask_index = mask_index + 4 * sign |
| 332 |
|
| 333 |
return mask_index |
| 334 |
|
| 335 |
|
| 336 |
def _compute_reflee_coefficients( |
| 337 |
span: np.ndarray, |
| 338 |
mask_index: np.ndarray, |
| 339 |
window_size: int, |
| 340 |
num_looks: int, |
| 341 |
) -> np.ndarray: |
| 342 |
eps = 1e-30 |
| 343 |
# compute local statistics |
| 344 |
mean_local = _convolve_and_select(span, mask_index, window_size) |
| 345 |
mean_local_sq = _convolve_and_select(span**2, mask_index, window_size) |
| 346 |
var_local = mean_local_sq - mean_local**2 |
| 347 |
sigma2 = 1 / num_looks |
| 348 |
cv_span2 = abs(var_local) / (eps + mean_local**2) |
| 349 |
coeff = (cv_span2 - sigma2) / (cv_span2 * (1 + sigma2) + eps) |
| 350 |
coeff = np.where(coeff < 0, 0, coeff) |
| 351 |
|
| 352 |
return coeff |
| 353 |
|
| 354 |
|
| 355 |
def _apply_reflee_filter( |
| 356 |
img: np.array, coeff: da.Array, mask_index: da.Array, window_size: int |
| 357 |
) -> dict: |
| 358 |
mean_local = _convolve_and_select(img, mask_index, window_size) |
| 359 |
filtered_img = mean_local + coeff * (img - mean_local) |
| 360 |
return filtered_img |
| 361 |
|
| 362 |
|
| 363 |
# convolves with all masks and selects according to index |
| 364 |
def _convolve_and_select(img, mask_index, window_size): |
| 365 |
# adds small overhead and avoids chunk alignment issues |
| 366 |
masks = _make_masks(window_size) |
| 367 |
mode = "constant" |
| 368 |
imgout = np.zeros((masks.shape[0],) + img.shape, dtype=img.dtype) |
| 369 |
msk = np.isnan(img) |
| 370 |
img_ = np.where(msk, 0, img) |
| 371 |
for i in np.arange(masks.shape[0]): |
| 372 |
ker = masks[i] |
| 373 |
if np.iscomplexobj(img_): |
| 374 |
imgout[i] = convolve(img_.real, ker, mode=mode) + 1j * convolve( |
| 375 |
img_.imag, ker, mode=mode |
| 376 |
) |
| 377 |
imgout[i][msk] = np.nan + 1j * np.nan |
| 378 |
else: |
| 379 |
imgout[i] = convolve(img_, ker, mode=mode) |
| 380 |
imgout[i][msk] = np.nan |
| 381 |
|
| 382 |
return _extract_value_at_indices(imgout, mask_index) |
| 383 |
|
| 384 |
|
| 385 |
# dask doesn't support ND fancy indexing |
| 386 |
def _extract_value_at_indices(arr: np.ndarray, indices: np.ndarray) -> np.ndarray: |
| 387 |
val = np.zeros_like(indices, dtype=arr.dtype) |
| 388 |
for i in np.arange(arr.shape[0]): |
| 389 |
val = np.where(indices == i, arr[i], val) |
| 390 |
return val |
| 391 |
|
| 392 |
|
| 393 |
def _compute_span(ds_in: xr.Dataset) -> da.Array: |
| 394 |
# directly return a dask array to avoid unnecessary conversions |
| 395 |
span = da.zeros_like(ds_in.m11.data) |
| 396 |
poltype = ds_in.poltype |
| 397 |
if poltype in ("C2", "T2"): |
| 398 |
span = ds_in.m11.data + ds_in.m22.data |
| 399 |
elif poltype in ("C3", "T3"): |
| 400 |
span = ds_in.m11.data + ds_in.m22.data + ds_in.m33.data |
| 401 |
elif poltype in ("C4", "T4"): |
| 402 |
span = ds_in.m11.data + ds_in.m22.data + ds_in.m33.data + ds_in.m44.data |
| 403 |
return span |
| 404 |
|
| 405 |
|
| 406 |
def _get_window_params(nw: int) -> tuple[int, int]: |
| 407 |
|
| 408 |
# compute for any allowed window sizes the corresponding |
| 409 |
# gradient window size and the subsampling step |
| 410 |
params = { |
| 411 |
3: (1, 1), |
| 412 |
5: (3, 1), |
| 413 |
7: (3, 2), |
| 414 |
9: (5, 2), |
| 415 |
11: (5, 3), |
| 416 |
13: (5, 4), |
| 417 |
15: (7, 4), |
| 418 |
17: (7, 5), |
| 419 |
19: (7, 6), |
| 420 |
21: (9, 6), |
| 421 |
23: (9, 7), |
| 422 |
25: (9, 8), |
| 423 |
27: (11, 8), |
| 424 |
29: (11, 9), |
| 425 |
31: (11, 10), |
| 426 |
} |
| 427 |
|
| 428 |
try: |
| 429 |
window_size_grad, sub = params[nw] |
| 430 |
except KeyError: |
| 431 |
raise ValueError("Window size must be one of {3, 5, 7, …, 31}") |
| 432 |
|
| 433 |
return window_size_grad, sub |
| 434 |
|
| 435 |
|
| 436 |
def _make_masks(window_size: int) -> np.array: |
| 437 |
if window_size % 2 == 0: |
| 438 |
raise ValueError("window_size must be odd") |
| 439 |
|
| 440 |
h = window_size // 2 |
| 441 |
grid_i, grid_j = np.meshgrid( |
| 442 |
np.arange(-h, h + 1, dtype=np.int32), |
| 443 |
np.arange(-h, h + 1, dtype=np.int32), |
| 444 |
indexing="ij", |
| 445 |
) |
| 446 |
|
| 447 |
# Masks (same order as original C Nmax indices) |
| 448 |
w0 = (grid_j >= 0).astype("float32") # right half |
| 449 |
w1 = (grid_j >= grid_i).astype("float32") # upper-right triangle |
| 450 |
w2 = (grid_i <= 0).astype("float32") # top half |
| 451 |
w3 = (grid_j <= grid_i)[::-1].astype("float32") # upper-left triangle |
| 452 |
w4 = (grid_j <= 0).astype("float32") # left half |
| 453 |
w5 = (grid_j <= grid_i).astype("float32") # lower-left triangle |
| 454 |
w6 = (grid_i >= 0).astype("float32") # bottom half |
| 455 |
w7 = (grid_j >= grid_i)[::-1].astype("float32") # lower-right triangle |
| 456 |
|
| 457 |
w0 /= np.sum(w0) |
| 458 |
w1 /= np.sum(w1) |
| 459 |
w2 /= np.sum(w2) |
| 460 |
w3 /= np.sum(w3) |
| 461 |
w4 /= np.sum(w4) |
| 462 |
w5 /= np.sum(w5) |
| 463 |
w6 /= np.sum(w6) |
| 464 |
w7 /= np.sum(w7) |
| 465 |
masks = np.stack([w0, w1, w2, w3, w4, w5, w6, w7], axis=0).astype("float32") |
| 466 |
|
| 467 |
return masks |