| 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 read / write functions |
| 27 |
|
| 28 |
""" |
| 29 |
|
| 30 |
import logging |
| 31 |
from pathlib import Path |
| 32 |
|
| 33 |
import numpy as np |
| 34 |
import xarray |
| 35 |
import xarray as xr |
| 36 |
|
| 37 |
from polsarpro.auxil import validate_dataset |
| 38 |
|
| 39 |
log = logging.getLogger(__name__) |
| 40 |
|
| 41 |
SLC_NO_TAG = "" |
| 42 |
ALLOWED_SLC_TAGS = ("S1", "S2", "S3") |
| 43 |
|
| 44 |
def open_netcdf_beam(file_path: str | Path) -> xarray.Dataset: |
| 45 |
"""Open data in the NetCDF-BEAM format exported by SNAP and create a valid python PolSARpro Dataset. Also works for complex matrix datasets written with polmat_to_netcdf. |
| 46 |
|
| 47 |
Args: |
| 48 |
file_path (str|Path): path of the input file. |
| 49 |
|
| 50 |
Returns: |
| 51 |
xarray.Dataset: output dataset with python PolSARpro specific metadata. |
| 52 |
|
| 53 |
Note: |
| 54 |
Only polarimetric data is allowed. |
| 55 |
Supported polarimetric types are 'S' scattering matrix, 'C3' and 'C4' covariance matrices, 'T3' and 'T4' coherency matrices as well as 'C2' dual-polarimetric covariance matrix. |
| 56 |
""" |
| 57 |
|
| 58 |
# use chunks to create dask instead of numpy arrays |
| 59 |
ds = xr.open_dataset(file_path, chunks={}) |
| 60 |
var_names = set(ds.data_vars) |
| 61 |
|
| 62 |
# file comes from SNAP, else assume python PolSARpro dataset |
| 63 |
if "poltype" not in ds.attrs: |
| 64 |
meta = ds.metadata.attrs |
| 65 |
# check if image is in the SAR geometry or in geographic coordinates |
| 66 |
is_geocoded = bool(meta["Abstracted_Metadata:is_terrain_corrected"]) |
| 67 |
|
| 68 |
T3_vars = { |
| 69 |
"T11", |
| 70 |
"T22", |
| 71 |
"T33", |
| 72 |
"T12_real", |
| 73 |
"T12_imag", |
| 74 |
"T13_real", |
| 75 |
"T13_imag", |
| 76 |
"T23_real", |
| 77 |
"T23_imag", |
| 78 |
} |
| 79 |
C2_vars = { |
| 80 |
"C11", |
| 81 |
"C22", |
| 82 |
"C12_real", |
| 83 |
"C12_imag", |
| 84 |
} |
| 85 |
C3_vars = { |
| 86 |
"C11", |
| 87 |
"C22", |
| 88 |
"C33", |
| 89 |
"C12_real", |
| 90 |
"C12_imag", |
| 91 |
"C13_real", |
| 92 |
"C13_imag", |
| 93 |
"C23_real", |
| 94 |
"C23_imag", |
| 95 |
} |
| 96 |
C4_vars = C3_vars.union( |
| 97 |
{ |
| 98 |
"C14_real", |
| 99 |
"C14_imag", |
| 100 |
"C24_real", |
| 101 |
"C24_imag", |
| 102 |
"C34_real", |
| 103 |
"C34_imag", |
| 104 |
"C44", |
| 105 |
} |
| 106 |
) |
| 107 |
T4_vars = T3_vars.union( |
| 108 |
{ |
| 109 |
"T14_real", |
| 110 |
"T14_imag", |
| 111 |
"T24_real", |
| 112 |
"T24_imag", |
| 113 |
"T34_real", |
| 114 |
"T34_imag", |
| 115 |
"T44", |
| 116 |
} |
| 117 |
) |
| 118 |
|
| 119 |
# S matrix - SLC is a special case as band names may vary |
| 120 |
tag = _parse_slc_bands(var_names) |
| 121 |
|
| 122 |
# infers polarimetric type from dataset variable names |
| 123 |
data = {} |
| 124 |
|
| 125 |
if C4_vars.issubset(var_names): |
| 126 |
poltype = "C4" |
| 127 |
description = "Covariance matrix (4x4)" |
| 128 |
data["m11"] = ds.C11 |
| 129 |
data["m22"] = ds.C22 |
| 130 |
data["m33"] = ds.C33 |
| 131 |
data["m44"] = ds.C44 |
| 132 |
data["m12"] = ds.C12_real + 1j * ds.C12_imag |
| 133 |
data["m13"] = ds.C13_real + 1j * ds.C13_imag |
| 134 |
data["m14"] = ds.C14_real + 1j * ds.C14_imag |
| 135 |
data["m23"] = ds.C23_real + 1j * ds.C23_imag |
| 136 |
data["m24"] = ds.C24_real + 1j * ds.C24_imag |
| 137 |
data["m34"] = ds.C34_real + 1j * ds.C34_imag |
| 138 |
elif C3_vars.issubset(var_names): |
| 139 |
poltype = "C3" |
| 140 |
description = "Covariance matrix (3x3)" |
| 141 |
data["m11"] = ds.C11 |
| 142 |
data["m22"] = ds.C22 |
| 143 |
data["m33"] = ds.C33 |
| 144 |
data["m12"] = ds.C12_real + 1j * ds.C12_imag |
| 145 |
data["m13"] = ds.C13_real + 1j * ds.C13_imag |
| 146 |
data["m23"] = ds.C23_real + 1j * ds.C23_imag |
| 147 |
elif C2_vars.issubset(var_names): |
| 148 |
poltype = "C2" |
| 149 |
description = "Covariance matrix (2x2)" |
| 150 |
data["m11"] = ds.C11 |
| 151 |
data["m22"] = ds.C22 |
| 152 |
data["m12"] = ds.C12_real + 1j * ds.C12_imag |
| 153 |
elif T4_vars.issubset(var_names): |
| 154 |
poltype = "T4" |
| 155 |
description = "Coherency matrix (4x4)" |
| 156 |
data["m11"] = ds.T11 |
| 157 |
data["m22"] = ds.T22 |
| 158 |
data["m33"] = ds.T33 |
| 159 |
data["m44"] = ds.T44 |
| 160 |
data["m12"] = ds.T12_real + 1j * ds.T12_imag |
| 161 |
data["m13"] = ds.T13_real + 1j * ds.T13_imag |
| 162 |
data["m14"] = ds.T14_real + 1j * ds.T14_imag |
| 163 |
data["m23"] = ds.T23_real + 1j * ds.T23_imag |
| 164 |
data["m24"] = ds.T24_real + 1j * ds.T24_imag |
| 165 |
data["m34"] = ds.T34_real + 1j * ds.T34_imag |
| 166 |
elif T3_vars.issubset(var_names): |
| 167 |
poltype = "T3" |
| 168 |
description = "Coherency matrix (3x3)" |
| 169 |
data["m11"] = ds.T11 |
| 170 |
data["m22"] = ds.T22 |
| 171 |
data["m33"] = ds.T33 |
| 172 |
data["m12"] = ds.T12_real + 1j * ds.T12_imag |
| 173 |
data["m13"] = ds.T13_real + 1j * ds.T13_imag |
| 174 |
data["m23"] = ds.T23_real + 1j * ds.T23_imag |
| 175 |
elif tag is not None: |
| 176 |
poltype = "S" |
| 177 |
description = "Scattering matrix" |
| 178 |
if tag == SLC_NO_TAG: # Usual SNAP band names |
| 179 |
data["hh"] = ds.i_HH + 1j * ds.q_HH |
| 180 |
data["hv"] = ds.i_HV + 1j * ds.q_HV |
| 181 |
data["vh"] = ds.i_VH + 1j * ds.q_VH |
| 182 |
data["vv"] = ds.i_VV + 1j * ds.q_VV |
| 183 |
else: # BIOMASS data |
| 184 |
data["hh"] = ds[f"i_{tag}_HH"] + 1j * ds[f"q_{tag}_HH"] |
| 185 |
data["hv"] = ds[f"i_{tag}_HV"] + 1j * ds[f"q_{tag}_HV"] |
| 186 |
data["vh"] = ds[f"i_{tag}_VH"] + 1j * ds[f"q_{tag}_VH"] |
| 187 |
data["vv"] = ds[f"i_{tag}_VV"] + 1j * ds[f"q_{tag}_VV"] |
| 188 |
else: |
| 189 |
raise ValueError( |
| 190 |
"Polarimetric type not recognized. Possible types are 'S', 'C2', 'C3', 'T3', 'C4', 'T4' matrices." |
| 191 |
) |
| 192 |
|
| 193 |
# make a new dataset with PolSARpro metadata |
| 194 |
if "poltype" not in ds.attrs: |
| 195 |
ds_out = xr.Dataset( |
| 196 |
data, attrs={"poltype": poltype, "description": description} |
| 197 |
) |
| 198 |
|
| 199 |
# coordinates: "y" & "x" for SAR geometry, "lat" & "lon" for geocoded |
| 200 |
if {"y", "x"}.issubset(ds.dims) and not is_geocoded: |
| 201 |
# make sure coordinates are only pixel indices |
| 202 |
return ds_out.assign_coords( |
| 203 |
{"y": np.arange(ds.sizes["y"]), "x": np.arange(ds.sizes["x"])} |
| 204 |
).drop_vars(("lon", "lat"), errors="ignore") |
| 205 |
else: |
| 206 |
return ds_out |
| 207 |
# input data was already a python PolSARpro dataset |
| 208 |
else: |
| 209 |
ds_out = xr.Dataset( |
| 210 |
data, |
| 211 |
attrs={"poltype": poltype, "description": description}, |
| 212 |
coords=ds.coords, |
| 213 |
) |
| 214 |
return ds_out |
| 215 |
|
| 216 |
|
| 217 |
def polmat_to_netcdf(ds: xarray.Dataset, file_path: str | Path): |
| 218 |
"""Writes complex polarimetric matrices to a nectdf file. |
| 219 |
Due to the lack of complex number support in netcdf files, real and imaginary parts are stored separately. |
| 220 |
Variable names follow the netcdf-beam convention used by SNAP. |
| 221 |
|
| 222 |
Args: |
| 223 |
ds (xarray.Dataset): input dataset with polarimetric matrix elements. |
| 224 |
file_path (str|Path): output file path. |
| 225 |
""" |
| 226 |
|
| 227 |
poltype = validate_dataset(ds, allowed_poltypes=["S", "C2", "C3", "T3", "C4", "T4"]) |
| 228 |
|
| 229 |
data_out = {} |
| 230 |
if poltype == "S": |
| 231 |
data_out["i_HH"] = ds.hh.real |
| 232 |
data_out["q_HH"] = ds.hh.imag |
| 233 |
data_out["i_HV"] = ds.hv.real |
| 234 |
data_out["q_HV"] = ds.hv.imag |
| 235 |
data_out["i_VH"] = ds.vh.real |
| 236 |
data_out["q_VH"] = ds.vh.imag |
| 237 |
data_out["i_VV"] = ds.vv.real |
| 238 |
data_out["q_VV"] = ds.vv.imag |
| 239 |
else: |
| 240 |
# automatically extract data for T and C matrices |
| 241 |
n = int(poltype[-1]) |
| 242 |
name = poltype[0] |
| 243 |
for i in range(1, n + 1): |
| 244 |
for j in range(i, n + 1): |
| 245 |
arr = ds[f"m{i}{j}"] |
| 246 |
if i == j: |
| 247 |
data_out[f"{name}{i}{j}"] = arr |
| 248 |
else: |
| 249 |
data_out[f"{name}{i}{j}_real"] = arr.real |
| 250 |
data_out[f"{name}{i}{j}_imag"] = arr.imag |
| 251 |
|
| 252 |
# make a new dataset with PolSARpro metadata |
| 253 |
# Preserve chunking when writing |
| 254 |
encoding = {var: {"chunksizes": data_out[var].data.chunksize, "zlib": True} for var in data_out} |
| 255 |
ds_out = xr.Dataset( |
| 256 |
# extract dask arrays and dims from xarray data |
| 257 |
{k: (ds.dims, v.data) for k, v in data_out.items()}, |
| 258 |
attrs={"poltype": poltype, "description": ds.description}, |
| 259 |
coords=ds.coords, |
| 260 |
) |
| 261 |
ds_out.to_netcdf(file_path, encoding=encoding) |
| 262 |
|
| 263 |
# --- helper functions not to be called outside of the module |
| 264 |
|
| 265 |
def _parse_slc_bands(var_names: set[str]) -> str | None: |
| 266 |
pol_list = ("HH", "HV", "VH", "VV") |
| 267 |
tags = ("S1", "S2", "S3") |
| 268 |
|
| 269 |
# Legacy SNAP-style SLC (no tag) |
| 270 |
base_set = {f"{x}_{p}" for p in pol_list for x in ("i", "q")} |
| 271 |
if base_set.issubset(var_names): |
| 272 |
return SLC_NO_TAG |
| 273 |
|
| 274 |
# Tagged SLC variants |
| 275 |
found_tags = [] |
| 276 |
for tag in tags: |
| 277 |
tagged_set = {f"{x}_{tag}_{p}" for p in pol_list for x in ("i", "q")} |
| 278 |
if tagged_set.issubset(var_names): |
| 279 |
found_tags.append(tag) |
| 280 |
|
| 281 |
if len(found_tags) > 1: |
| 282 |
raise ValueError( |
| 283 |
f"Multiple SLC tags found: {found_tags}" |
| 284 |
) |
| 285 |
|
| 286 |
if found_tags: |
| 287 |
return found_tags[0] |
| 288 |
|
| 289 |
# Not an SLC dataset |
| 290 |
return None |
| 291 |
|
| 292 |
def get_incidence_angle_netcdf_beam(file_in: str | Path, interpolation_method:str = "linear") -> xr.Dataset: |
| 293 |
"""Extract the incidence angle raster from a SNAP NetCDF-BEAM file. |
| 294 |
|
| 295 |
Args: |
| 296 |
file_in (str | Path): NetCDF-BEAM file produced with SNAP. |
| 297 |
interpolation_method (str): interpolation method passed to xarray.Dataset.interp. |
| 298 |
|
| 299 |
Returns: |
| 300 |
xarray.Dataset: incidence angle interpolated to the raster grid. |
| 301 |
|
| 302 |
Note: |
| 303 |
This is a helper function that interpolates incidence angle from the tie point grid to the raster grid in SLC products. For geocoded products this function is not relevant since various incidence angles can be directly computed with SNAP Range Doppler Terrain Correction. |
| 304 |
""" |
| 305 |
ds = xr.open_dataset(file_in) |
| 306 |
|
| 307 |
if "incident_angle" not in ds: |
| 308 |
raise ValueError("Input dataset does not contain an 'incident_angle' variable.") |
| 309 |
if "metadata" not in ds: |
| 310 |
raise ValueError("Input dataset does not contain SNAP metadata.") |
| 311 |
|
| 312 |
ia = ds.incident_angle.rename(tp_y="y", tp_x="x") |
| 313 |
|
| 314 |
# raster dimensions |
| 315 |
meta = ds.metadata.attrs |
| 316 |
required_attrs = ( |
| 317 |
"Abstracted_Metadata:num_samples_per_line", |
| 318 |
"Abstracted_Metadata:num_output_lines", |
| 319 |
) |
| 320 |
missing_attrs = [attr for attr in required_attrs if attr not in meta] |
| 321 |
if missing_attrs: |
| 322 |
raise ValueError(f"SNAP metadata is missing required attribute(s): {missing_attrs}") |
| 323 |
nrg = meta["Abstracted_Metadata:num_samples_per_line"] |
| 324 |
naz = meta["Abstracted_Metadata:num_output_lines"] |
| 325 |
|
| 326 |
# tie point to raster coordinates |
| 327 |
coords_x = (ia.offset_x + ia.x) * ia.subsampling_x |
| 328 |
coords_y = (ia.offset_y + ia.y) * ia.subsampling_y |
| 329 |
|
| 330 |
# interpolate on new coordinates |
| 331 |
return ia.assign_coords(y=coords_y, x=coords_x).interp( |
| 332 |
y=np.arange(naz), |
| 333 |
x=np.arange(nrg), |
| 334 |
method=interpolation_method, |
| 335 |
kwargs={"fill_value": "extrapolate"}, |
| 336 |
).drop_attrs() |