Skip to content

polsarpro.classification

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, 2026. 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 classification functions

wishart_h_a_alpha(input_data, boxcar_size=[5, 5], h_a_alpha_result=None, max_iter=10, tol_pct=None, verbose=True)

Performs the Wishart H/A/Alpha classification on polarimetric SAR data.

This function implements an iterative unsupervised classification scheme based on the H/A/Alpha decomposition and the Wishart distance measure. The algorithm: 1. Computes initial H/A/Alpha decomposition parameters 2. Performs initial classification using the H-Alpha decision boundaries 3. Iteratively refines the classification using Wishart distance to 8 class centers 4. Split the 8 classes into 16 based on a 0.5 threshold on anisotropy 5. Apply Wishart iterations on these classes

Parameters:

Name Type Description Default
input_data Dataset

Input polarimetric SAR dataset. Supported types are:

  • "S": Sinclair scattering matrix

  • "C3": Lexicographic covariance matrix (3x3)

  • "T3": Pauli coherency matrix (3x3)

  • "C4": 4x4 covariance matrix

  • "T4": 4x4 coherency matrix

 required
boxcar_size list[int, int]

Size of the spatial averaging window (boxcar filter) applied before decomposition. Defaults to [5, 5].

 [5, 5]
h_a_alpha_result Dataset

Pre-computed H/A/Alpha decomposition results. If provided, the function will use these results for the initial H-Alpha classification instead of computing them from input_data. The dataset must contain at least 'entropy' and 'alpha' variables. If None (default), the H/A/Alpha decomposition is computed from input_data.

 None
max_iter int

Maximum number of iterations for the classification refinement loop. Must be a positive integer. Defaults to 10.

 10
tol_pct float or None

Threshold for early stopping based on the percentage of pixels changing class between iterations. This parameter is kept only for compatibility with the C version (see notes below). When the percentage of pixels that switch class is less than this value, the algorithm stops. If set, must be in the range [0.0, 100.0]. Defaults to None.

 None
verbose bool

If True, print progress messages during the eager tol_pct path. Defaults to True.

 True

Returns:

Type Description
Dataset

xr.Dataset: Dataset containing the 8 and 18 class maps. Pixels where any input polarimetric element is NaN are excluded from class-center estimation and iterative class assignment, and are encoded as class 0 in the output maps.
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.

Notes

It is recommended to leave the tol_pct parameter to its default None state to take advantage of Dask lazy processing. Setting this parameter to a value might result in a performance loss. It has been observed that without early termination the python implementation is faster than the legacy version.

For large products, calling this function without h_a_alpha_result can still require substantial memory when the lazy result is eventually computed or written to disk, because the H/A/Alpha decomposition is part of the same Dask pipeline. If memory is limited, compute the H/A/Alpha decomposition separately, write it to a file, reopen it with xarray, and pass it through h_a_alpha_result.

wishart_supervised(input_data, training_labels, boxcar_size=[5, 5])

Performs Wishart supervised classification based on user inputs. Args: input_data (xr.Dataset): Input polarimetric SAR dataset. Supported types are: - "S": Sinclair scattering matrix - "C3": Lexicographic covariance matrix (3x3) - "T3": Pauli coherency matrix (3x3) - "C4": 4x4 covariance matrix - "T4": 4x4 coherency matrix training_labels: (xr.DataArray): 2D array of the same spatial dimensions as input_data, containing integer class labels for training pixels. Each connected region for a class is used as a separate training cluster. Pixels with label 0 are considered unlabeled and are not used in training. boxcar_size (list[int, int], optional): Size of the spatial averaging window (boxcar filter) applied before decomposition. Defaults to [5, 5].

Returns:

Type Description
Dataset

xr.Dataset: Dataset containing the output classes. Pixels where any input polarimetric element is NaN are excluded from training and class assignment, and are encoded as class 0 in the output map.