Debian Codegraph @

polsarpro/speckle_filters.py

raw
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