polsarpro.decompositions
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 polarimetric decomposition functions
cameron(input_data)
Applies the Cameron decomposition to the S matrix.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
input_data
|
Dataset
|
Input image of S matrices. |
required |
Returns:
| Type | Description |
|---|---|
Dataset
|
xr.Dataset: Output class (1: plane, 2: dihedral, 3: dipole, 4: cylinder, 5: narrow diplane, 6: 1/4 wave, 7: left helix, 8: right helix). |
Notes
This decomposition is only applicable to Sinclair matrices (S). Therefore it may not be applied to geocoded data since resampling the S matrix may result in a loss of polarimetric information.
freeman(input_data, boxcar_size=[3, 3])
Applies the Freeman-Durden decomposition. This decomposition is based on physical modeling of the covariance matrix and returns 3 components Ps, Pd and Pv which are the powers of resp. surface, double bounce and volume backscattering.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
input_data
|
Dataset
|
Input image, may be a covariance (C3), coherency (T3) or Sinclair (S) matrix. |
required |
boxcar_size
|
list[int, int]
|
Boxcar dimensions along azimuth and range. Defaults to [3, 3]. |
[3, 3]
|
Returns:
| Type | Description |
|---|---|
Dataset
|
xr.Dataset: Ps, Pd and Pv components. |
References
Freeman A. and Durden S., “A Three-Component Scattering Model for Polarimetric SAR Data”, IEEE Trans. Geosci. Remote Sens., vol. 36, no. 3, May 1998.
h_a_alpha(input_data, boxcar_size=[3, 3], flags=('entropy', 'alpha', 'anisotropy'))
Performs the H/A/Alpha polarimetric decomposition on full-pol SAR data.
This function computes the H/A/Alpha decomposition from input polarimetric SAR data using eigenvalue analysis of the coherency matrix. The decomposition provides physical insight into scattering mechanisms through parameters such as entropy (H), anisotropy (A), and the alpha scattering angle (alpha). Additional eigenvalue-based parameters can also be computed by specifying corresponding flags.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
input_data
|
Dataset
|
Input polarimetric SAR dataset. Supported types are:
|
required |
boxcar_size
|
list[int, int]
|
Size of the spatial averaging window to be applied before decomposition (boxcar filter). Defaults to [3, 3]. |
[3, 3]
|
flags
|
tuple[str]
|
Parameters to compute and return from the decomposition. Possible values include:
|
('entropy', 'alpha', 'anisotropy')
|
Returns:
| Type | Description |
|---|---|
Dataset
|
xr.Dataset: An xarray.Dataset where data variable names correspond to the requested flags, and values are the corresponding 2D arrays (or 3D if the flag returns multiple values per pixel). |
Notes
For C2 inputs, only 'alpha(s)', 'delta(s)', 'anisotropy', 'entropy' and 'lambda(s)' can be computed. Other passed flags will be ignored.
If the S matrix is given as an input, a 3x3 analysis will be assumed using the T3 matrix. For 4x4 and 2x2, use 'C4', 'T4' or 'C2' as an input.
References
Cloude, S. R., & Pottier, E. (1997). An entropy based classification scheme for land applications of polarimetric SAR. IEEE Transactions on Geoscience and Remote Sensing, 35(1), 68-78.
tsvm(input_data, boxcar_size=[3, 3], flags=('alpha_phi_tau_psi',))
Applies the TSVM decomposition.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
input_data
|
Dataset
|
Input image, may be a covariance (C3), coherency (T3) or Sinclair (S) matrix. |
required |
boxcar_size
|
list[int, int]
|
Boxcar dimensions along azimuth and range. Defaults to [3, 3]. |
[3, 3]
|
flags
|
tuple[str]
|
Parameters to compute and return from the decomposition. Possible values include:
|
('alpha_phi_tau_psi',)
|
Returns:
| Type | Description |
|---|---|
Dataset
|
xr.Dataset: An xarray.Dataset where data variable names depend the requested flags, and values are the corresponding 2D arrays. |
Notes
Output variables have the same names as in the original PolSARpro C version. "alpha_s", "phi_s", "psi", "tau_m" followed by 1, 2 or 3 in the case of per-eigenvalue parameters.
vanzyl(input_data, boxcar_size=[3, 3])
Applies the Van Zyl 1992 3-component decomposition. This decomposition is based on physical modeling of the covariance matrix and returns 3 components Ps, Pd and Pv which are the powers of resp. surface, double bounce and volume backscattering.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
input_data
|
Dataset
|
Input image, may be a covariance (C3), coherency (T3) or Sinclair (S) matrix. |
required |
boxcar_size
|
list[int, int]
|
Boxcar dimensions along azimuth and range. Defaults to [3, 3]. |
[3, 3]
|
Returns:
| Type | Description |
|---|---|
Dataset
|
xr.Dataset: Ps, Pd and Pv components. |
References
Jakob J. van Zyl, Yunjin Kim, Synthetic Aperture Radar Polarimetry, Wiley; 1st edition (October 14, 2011), ISBN-10 1-118-11511-2, ISBN-13 978-1118115114
yamaguchi3(input_data, boxcar_size=[3, 3])
Applies the Yamaguchi 3 component decomposition. This decomposition is based on physical modeling of the covariance matrix and returns 3 components "odd", "surface" and "volume" which are the powers of resp. surface, double bounce and volume backscattering.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
input_data
|
Dataset
|
Input image, may be a covariance (C3), coherency (T3) or Sinclair (S) matrix. |
required |
boxcar_size
|
list[int, int]
|
Boxcar dimensions along azimuth and range. Defaults to [3, 3]. |
[3, 3]
|
Returns:
| Type | Description |
|---|---|
Dataset
|
xr.Dataset: odd, surface and volume scattering components. |
References
Yamaguchi Y., Moriyama T., Ishido M. and Yamada H., “Four-Component Scattering Model for Polarimetric SAR Image Decomposition”, IEEE Trans. Geos. Remote Sens., vol. 43, no. 8, August 2005.
yamaguchi4(input_data, boxcar_size=[3, 3], mode='y4o')
Applies the Yamaguchi 4 component decomposition. This decomposition is based on physical modeling of the covariance matrix and returns 4 components "odd", "surface", "volume" and "helix" which are the powers of resp. surface, double bounce, volume and helix backscattering.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
input_data
|
Dataset
|
Input image, may be a covariance (C3), coherency (T3) or Sinclair (S) matrix. |
required |
boxcar_size
|
list[int, int]
|
Boxcar dimensions along azimuth and range. Defaults to [3, 3]. |
[3, 3]
|
mode
|
str
|
One of the following modes "y4o" (original), "y4r" (with rotation) or "s4r" (). Defaults to "y4o". |
'y4o'
|
Returns:
| Type | Description |
|---|---|
Dataset
|
xr.Dataset: odd, surface, volume and helix scattering components. |
References
Yamaguchi Y., Moriyama T., Ishido M. and Yamada H., “Four-Component Scattering Model for Polarimetric SAR Image Decomposition”, IEEE Trans. Geos. Remote Sens., vol. 43, no. 8, August 2005.