Debian Codegraph @

polsarpro/io.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 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()