polsarpro.util
This code is part of the Python PolSARpro software:
"A re-implementation of selected PolSARPro functions in Python, following the scientific recommendations of PolInSAR 2021"
developed within an ESA funded project with SATIM.
Author: Olivier D'Hondt, 2025. Scientific advisors: Armando Marino and Eric Pottier.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Description: module containing various utility functions
C3_to_T3(C3)
Converts the lexicographic covariance matrix C3 to the Pauli coherency matrix T3.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
C3
|
Dataset
|
input image of covariance matrices |
required |
Returns:
| Type | Description |
|---|---|
Dataset
|
xarray.Dataset: T3 coherency matrix |
C4_to_C3(C4)
Converts the lexicographic covariance matrix C4 to the lexicographic covariance matrix C3.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
C4
|
Dataset
|
input image of covariance matrices |
required |
Returns:
| Type | Description |
|---|---|
Dataset
|
xarray.Dataset: C3 covariance matrix |
C4_to_T3(C4)
Converts the lexicographic covariance matrix C4 to the Pauli coherency matrix T3.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
C4
|
Dataset
|
input image of covariance matrices |
required |
Returns:
| Type | Description |
|---|---|
Dataset
|
xarray.Dataset: T3 coherency matrix |
C4_to_T4(C4)
Converts the lexicographic covariance matrix C4 to the Pauli coherency matrix T4.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
C4
|
Dataset
|
input image of covariance matrices |
required |
Returns:
| Type | Description |
|---|---|
Dataset
|
xarray.Dataset: T4 coherency matrix |
S_to_C2(S, p1='hh', p2='hv')
Converts the Sinclair scattering matrix S to the lexicographic dual polarization covariance matrix C2.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
S
|
Dataset
|
input image of scattering matrices |
required |
p1
|
str
|
first polarization. |
'hh'
|
p2
|
str
|
second polarization. |
'hv'
|
Returns:
| Type | Description |
|---|---|
Dataset
|
xarray.Dataset: C2 covariance matrix |
Note: p1 and p2 must be different and belong to {'hh', 'hv', 'vv', 'vh'}
S_to_C3(S)
Converts the Sinclair scattering matrix S to the lexicographic covariance matrix C3.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
S
|
Dataset
|
input image of scattering matrices |
required |
Returns:
| Type | Description |
|---|---|
Dataset
|
xarray.Dataset: C3 covariance matrix |
S_to_C4(S)
Converts the Sinclair scattering matrix S to the lexicographic covariance matrix C4.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
S
|
Dataset
|
input image of scattering matrices |
required |
Returns:
| Type | Description |
|---|---|
Dataset
|
xarray.Dataset: C4 covariance matrix |
S_to_T3(S)
Converts the Sinclair scattering matrix S to the Pauli coherency matrix T3.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
S
|
Dataset
|
input image of scattering matrices |
required |
Returns:
| Type | Description |
|---|---|
Dataset
|
xarray.Dataset: T3 covariance matrix |
S_to_T4(S)
Converts the Sinclair scattering matrix S to the Pauli coherency matrix T4.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
S
|
Dataset
|
input image of scattering matrices |
required |
Returns:
| Type | Description |
|---|---|
Dataset
|
xarray.Dataset: T4 coherency matrix |
T3_to_C3(T3)
Converts the Pauli coherency matrix T3 to the lexicographic covariance matrix C3.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
T3
|
Dataset
|
input image of coherency matrices |
required |
Returns:
| Type | Description |
|---|---|
Dataset
|
xarray.Dataset: C3 covariance matrix |
T4_to_C3(T4)
Converts the Pauli coherency matrix T4 to the lexicographic covariance matrix C3.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
T4
|
Dataset
|
input image of coherency matrices |
required |
Returns:
| Type | Description |
|---|---|
Dataset
|
xarray.Dataset: C3 covariance matrix |
T4_to_C4(T4)
Converts the Pauli coherency matrix T4 to the lexicographic covariance matrix C4.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
T4
|
Dataset
|
input image of coherency matrices |
required |
Returns:
| Type | Description |
|---|---|
Dataset
|
xarray.Dataset: C4 covariance matrix |
T4_to_T3(T4)
Converts the Pauli coherency matrix T4 to the Pauli coherency matrix T3.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
T4
|
Dataset
|
input image of coherency matrices |
required |
Returns:
| Type | Description |
|---|---|
Dataset
|
xarray.Dataset: T3 coherency matrix |
boxcar(img, dim_az, dim_rg)
Apply a boxcar filter to an image.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
img
|
Dataset
|
Input image with variables of shape (naz, nrg, ...). |
required |
dim_az
|
int
|
Size in azimuth of the filter. |
required |
dim_rg
|
int
|
Size in range of the filter. |
required |
Returns:
| Type | Description |
|---|---|
Dataset
|
xarray.Dataset: Filtered image, shape (naz, nrg, ...). |
Note
The filter is always applied along 2 dimensions (azimuth, range). Please ensure to provide a valid image.
multilook(input_data, dim_az=2, dim_rg=2)
Apply multilooking to polarimetric matrices.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
input_data
|
Dataset
|
Input PolSARpro Dataset. |
required |
dim_az
|
int
|
Multilook dimension in azimuth. |
2
|
dim_rg
|
int
|
Multilook dimension in range. |
2
|
Returns:
| Type | Description |
|---|---|
Dataset
|
xr.Dataset: Multilooked PolSARpro Dataset. |
Note
The input dataset must be in the SAR geometry (i.e. have 'y' and 'x' coordinates).
pauli_rgb(input_data, q=0.98)
Compute Pauli RGB representation from polarimetric data.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
input_data
|
Dataset
|
Input PolSARpro Dataset. |
required |
q
|
float
|
Quantile for dynamic range clipping (between 0 and 1). |
0.98
|
Returns:
| Type | Description |
|---|---|
DataArray
|
xr.DataArray: RGB representation with 'band' dimension. |
plot_h_alpha_plane(ds, bins=500, min_pts=5)
Plot H-Alpha 2D histogram.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ds
|
Dataset
|
Dataset containing 'entropy' and 'alpha' variables. |
required |
bins
|
int
|
Number of bins along each dimension. |
500
|
min_pts
|
int
|
If the number of points in one bin is less than this value, display is omitted. |
5
|