polsardp 0.1.4

No project description provided

polsardp - Polarimetric SAR Data Processing Package

Closed-source Python implementation of algorithms for fully polarimetric SAR data, including incoherent polarimetric decomposition, deorientation, orientation angle rotation and helix angle rotation, et al. Closed-source Python implementation of algorithms for compact polarimetric SAR data, including incoherent compact polarimetric decomposition and conversion from fully polarimetric T matrix to compact polarimetric Stokes g vector, et al.

---

Introduction

polsardp is a commercial-grade algorithm library dedicated to polarimetric SAR data processing, developed by Wentao An based on years of research achievements in polarimetric SAR data processing. This library provides industry-leading target decomposition algorithms for fully polarimetric and compact polarimetric SAR data, and supports core operations such as orientation angle rotation, helix angle rotation and deorientation. All algorithms have undergone rigorous theoretical verification and practical data tests, featuring high computational efficiency and reliable results.

This library provides user-friendly Python interfaces for researchers and engineers to integrate and use quickly. More functions will be continuously updated in the follow-up, including filtering, import of data from typical satellite platforms and target detection applications, to build an all-in-one solution for polarimetric SAR data processing.

⚠️Copyright Declaration

Copyright © [Wentao An] [2026] This software (polsardp) is licensed under the CC BY-NC 4.0 License Official License Link: https://creativecommons.org/licenses/by-nc/4.0/

1. Non-Commercial Use Terms: Free for personal learning, academic research, teaching and public welfare projects. This copyright notice must be retained, and the author and source shall be credited when using this software.
2. Commercial Use Restrictions: Any commercial use, including personal commercial applications, enterprise deployment, profit-making projects and paid services, requires purchasing a commercial license by contacting the author. Commercial License Contact: Email: [e-mail] QQ: 85371297

---

Core Features

Implemented Functions

✅ Incoherent polarimetric target decomposition for fully polarimetric SAR (dozens of mainstream algorithms supported) ✅ Incoherent compact polarimetric target decomposition for compact polarimetric SAR (only applicable to compact polarimetric data with circular polarization transmission and HV linear polarization reception) ✅ Orientation angle rotation and deorientation processing ✅ Helix angle rotation and helix angle compensation processing ✅ Polarimetric matrix conversion (Coherency matrix T, Covariance matrix C, Kennaugh matrix K, Pauli vector k, Scattering matrix S, compact polarimetric Stokes vector g, etc. The library mainly processes data based on matrix T) ✅ Visualization of polarimetric power and amplitude images

Planned Updates

🔄 Polarimetric SAR data filtering (Nonlocal filter, etc.) 🔄 Import and export of data from mainstream SAR satellites (including GF-3 series satellites) 🔄 Marine target detection and recognition,etc.

---

Installation

System Requirements

Operating System: Windows 10/11 64-bit Python Version: 3.11.x or 3.12.x (64-bit) Dependencies: NumPy ≥ 1.24.0 (developed with version 1.26.4), Matplotlib ≥ 3.7.0 (developed with version 3.10.8, for visualization only)

Installation Commands

# Install the latest version
pip install --upgrade polsardp
# Install a specified version
pip install polsardp==0.1.1

---

Function Usage

General Import Methods

Two standard import methods are available for your preference:

1. Import the entire package (recommended for multiple function calls)

import polsardp as pdp
result = pdp.function_name(parameters)

2. Import specified functions individually (concise for single-function use)

from polsardp import polsar_decompose
result = polsar_decompose(parameters)

---

User Feedback Channels

We provide two repositories for technical communication, all problems are accepted via Issues:

1. Global Access Repository (GitHub) Link: https://github.com/WentaoAn-pdp/polsardp Suitable for overseas researchers and users with normal international network.

2. Domestic High-Speed Repository (Gitee) Link: https://gitee.com/wentao-an/polsardp Optimized for users in Chinese mainland with faster loading speed.

Submission Tips

• Submit an Issue for runtime crashes, error logs, algorithm parameter questions and new function demands.
• Do not upload unprocessed confidential measurement data or personal privacy content, as all Issue content is open to the public.

---

Version Changelog

v0.1.0 (Latest internal test version)

1. Added functions for calculating polarimetric entropy H, polarimetric alpha angle and polarimetric hq parameters
2. Optimized algorithm kernel; ready for academic research and practical data processing

v0.0.3

1. Added conversion functions between various polarimetric matrices and vectors, including polarimetric scattering matrix S, Pauli vector k, coherency matrix T, covariance matrix C, Kennaugh matrix K and compact polarimetric Stokes vector g. Polarimetric Mueller matrix: M = np.diag([1,1,1,-1]) @ K
2. Four-component decomposition algorithms

#【1】Implementation of classic Yamaguchi four-component polarimetric decomposition
result = polsar_decompose(data, "Y4D")
#【2】Implementation of deorientation-based Yamaguchi four-component polarimetric decomposition
result = polsar_decompose(data, "Y4R")
#【3】Implementation of G4U four-component polarimetric decomposition
result = polsar_decompose(data, "G4U")
#【4】Implementation of Polarimetric Symmetry four-component decomposition Version 1
result = polsar_decompose(data, "PSDv1")
#【5】Implementation of Polarimetric Symmetry four-component decomposition Version 2
result = polsar_decompose(data, "PSDv2")

v0.0.2

1. Added fully polarimetric SAR decomposition function (polsar_decompose)
2. Added compact polarimetric decomposition function (compact_decompose)
3. Added 10 utility functions for rotation, deorientation and de-helix processing
4. Added image visualization functions

v0.0.1 Initial placeholder version with no practical functions, for package structure test only

---

Run the Built-in Demo （recommended）

To quickly get started and understand how to use this package, we provide a ready-to-use demo script together with sample SAR data.

1. The demo file demo.py and sample data GF3_Barnaul_Demo.npy are integrated into the installed package, no extra files are required.
2. Execute the following command in your terminal to run the demo:

python -m polsardp.demo

3. What the demo does: Load the embedded sample polarimetric SAR data. Perform multiple classic polarimetric decomposition methods. Display visualization results. Validate data inversion and deorientation algorithms.

The demo.py file (as follows) is located in the installation directory of the polsardp package. We strongly recommend you read through the source code of this demo carefully. It covers the core calling methods and typical workflows, which will help you master the usage of this package efficiently.

# Import required libraries
import numpy as np
import matplotlib.pyplot as plt
import polsardp as pdp
import os

# Get the installation directory of polsardp package
pkg_dir = os.path.dirname(pdp.__file__)
# Construct full path of the sample NPY data file
npy_path = os.path.join(pkg_dir, "GF3_Barnaul_Demo.npy")
# Load sample SAR data and convert data type to double (float64)
data = np.load(npy_path).astype(np.float64)

# -------------------------- F3R Decomposition --------------------------
# Execute F3R polarimetric decomposition
outP = pdp.polsar_decompose(data, "F3R")
# Visualize decomposition results with different display modes
z = pdp.fSpanImShow2(outP['Ps'], outP['Pd'], outP['Pv'], -1)
z = pdp.fSpanImShow2(outP['Ps'], outP['Pd'], outP['Pv'], -1, [])

# -------------------------- RSD Decomposition --------------------------
# Execute RSD polarimetric decomposition
outP = pdp.polsar_decompose(data, "RSD")
# Set display parameter
imageK = 0
# Visualize decomposition results
z = pdp.fSpanImShow0(outP['Ps'], outP['Pd'], outP['Pv'], imageK-3)
z = pdp.fSpanImShow0(outP['Ps'], outP['Pd'], outP['Pv'], imageK, [])

# -------------------------- RIRSA Decomposition & Inversion --------------------------
# Execute RIRSA polarimetric decomposition
outP = pdp.polsar_decompose(data, "RIRSA")
# Visualize RIRSA decomposition results
z = pdp.fSpanImShow0(outP['Ps'], outP['Pd'], outP['Pv'], imageK-3)
z = pdp.fSpanImShow0(outP['Ps'], outP['Pd'], outP['Pv'], imageK, [])

# Perform RIRSA inversion calculation
dataInv, dataV, data2, dataR = pdp.f_RIRSA_Inv0(outP)
# Calculate maximum absolute error between original and inverted data
print(np.max(np.abs(data - dataInv)))

# -------------------------- MMA Compact Decomposition --------------------------
# Set compact polarization index
indexRL = 2
# Convert original data to compact polarimetric Stokes vector g
g0, g1, g2, g3 = pdp.fT2G(data, indexRL)
# Execute MMA compact polarimetric decomposition
outP = pdp.compact_decompose(g0, g1, g2, g3, indexRL, "mma")
# Visualize MMA decomposition results
z = pdp.fSpanImShow0(outP['Ps'], outP['Pd'], outP['Pv'], imageK-3)
z = pdp.fSpanImShow0(outP['Ps'], outP['Pd'], outP['Pv'], imageK, [])

# -------------------------- Deorientation & Rotation Validation --------------------------
# Execute polarimetric deorientation processing
data0, theta = pdp.fDeorientation0(data)
# Rotate data back with the calculated angle
dataT = pdp.fOrientationAngleRotation(data0, -theta)
# Calculate maximum absolute error before and after rotation
print(np.max(np.abs(data - dataT)))

# Display all generated figures
plt.show()

---

---

List of Public Core Functions & Usage Examples

---

fOrientationAngleRotation - Polarimetric Orientation Angle Rotation (Inverse Rotation)

Function: Perform inverse rotation of polarimetric orientation angle on the coherency matrix T of fully polarimetric SAR data Note: Inverse rotation refers to the rotation opposite to the positive increase of orientation angle. This definition is adopted because the acquired observed data has already undergone rotation. The inverse rotation gradually reduces and eliminates the orientation angle, which is consistent with deorientation operation.

Input Parameters:

T: 3D NumPy array with shape [Height, Width, 9] Standard channel order for matrix T in this library: T[...,0] = T11 T[...,1] = T22 T[...,2] = T33 T[...,3] = Re(T12) T[...,4] = Re(T13) T[...,5] = Re(T23) T[...,6] = Im(T12) T[...,7] = Im(T13) T[...,8] = Im(T23) phi: Rotation angle parameter (equal to 2*theta, where theta is the orientation angle), unit: radian Note: To perform positive orientation angle rotation, assign a negative value to phi.

Output:

Return the coherency matrix T after rotation (new array; original input data will not be modified)

Import Method:

from polsardp import fOrientationAngleRotation

Usage Example:

import numpy as np
from polsardp import fOrientationAngleRotation

# Load fully polarimetric T matrix data
T_matrix = np.random.rand(5, 5, 9).astype(np.float64)

# Set rotation angle phi (radian)
phi = np.pi/4

# Perform inverse orientation angle rotation
T_rotated = fOrientationAngleRotation(T_matrix, phi)
#Print output shape
print("Shape of rotated T matrix:", T_rotated.shape)

---

fDeorientation0 - Polarimetric Data Deorientation

Function: Perform deorientation on the coherency matrix T of fully polarimetric SAR data. The function automatically calculates the orientation angle and completes inverse rotation correction. It outputs the coherency matrix with zero orientation angle and the original orientation angle of input T matrix.

Input Parameters:

datain: 3D NumPy array with shape (Height, Width, 9) Standard polarimetric coherency matrix T with the following channel order: datain[...,0] = T11 datain[...,1] = T22 datain[...,2] = T33 datain[...,3] = Re(T12) datain[...,4] = Re(T13) datain[...,5] = Re(T23) datain[...,6] = Im(T12) datain[...,7] = Im(T13) datain[...,8] = Im(T23)

Output:

T: Coherency matrix after deorientation (new array; original input will not be modified) phi: Calculated orientation angle parameter (equal to 2theta), unit: radian phi = 2theta, value range: (-pi/2, pi/2] Note: the reason why phi is 2 times the orientation angle is to calculate quickly

Import Method:

from polsardp import fDeorientation0

Usage Example:

import numpy as np
from polsardp import fDeorientation0

# Load fully polarimetric T matrix data
T_matrix = np.load("your_t_matrix_data.npy")

# Perform deorientation
T_processed, phi = fDeorientation0(T_matrix)
Print output information
print("Shape of processed T matrix:", T_processed.shape)
print("Shape of orientation angle phi:", phi.shape)

---

fHelixAngleRotation - Polarimetric Helix Angle Rotation (Forward Rotation)

Function: Perform helix angle rotation on the coherency matrix T of fully polarimetric SAR data

Input Parameters:

T: 3D NumPy array with shape [Height, Width, 9] Standard channel order for matrix T in this library: T[...,0] = T11 T[...,1] = T22 T[...,2] = T33 T[...,3] = Re(T12) T[...,4] = Re(T13) T[...,5] = Re(T23) T[...,6] = Im(T12) T[...,7] = Im(T13) T[...,8] = Im(T23) phi: Rotation angle parameter (equal to 2*theta, theta denotes helix angle). phi represents twice the actual rotation angle for computational efficiency, unit: radian

Output:

Return the coherency matrix T after rotation (new array; original input data will not be modified)

Import Method:

from polsardp import fHelixAngleRotation

Usage Example:

import numpy as np
from polsardp import fHelixAngleRotation

#Load fully polarimetric T matrix data
T_matrix = np.random.rand(5, 5, 9).astype(np.float64)

#Set rotation angle phi (radian)
phi = np.pi/8

#Perform helix angle rotation
T_rotated = fHelixAngleRotation(T_matrix, phi)
#Print output shape
print("Shape of rotated T matrix:", T_rotated.shape)

---

fDeHelixAngle - Polarimetric Data helix angle compensation Processing

Function: Perform helix angle compensation operation on the coherency matrix T of fully polarimetric SAR data. The function automatically calculates the helix angle and completes inverse rotation correction. It outputs the coherency matrix with zero helix angle and the original helix angle of input T matrix.

Input Parameters:

datain: 3D NumPy array with shape (Height, Width, 9) Standard polarimetric coherency matrix T with the following channel order: datain[...,0] = T11 datain[...,1] = T22 datain[...,2] = T33 datain[...,3] = Re(T12) datain[...,4] = Re(T13) datain[...,5] = Re(T23) datain[...,6] = Im(T12) datain[...,7] = Im(T13) datain[...,8] = Im(T23)

Output:

T: Coherency matrix after de-helix processing (new array; original input will not be modified) phi: Calculated helix angle parameter (equal to 2theta), unit: radian phi = 2theta, value range: (-pi/2, pi/2]

Import Method:

from polsardp import fDeHelixAngle

Usage Example:

import numpy as np
from polsardp import fDeHelixAngle

#Load fully polarimetric T matrix data
T_matrix = np.load("your_t_matrix_data.npy")

#Perform de-helix processing
T_processed, phi = fDeHelixAngle(T_matrix)
#Print output information
print("Shape of processed T matrix:", T_processed.shape)
print("Shape of helix angle phi:", phi.shape)

---

polsar_decompose - Main Entry for Fully Polarimetric SAR Incoherent Decomposition

Function: Unified main entry for incoherent polarimetric decomposition of fully polarimetric SAR data. Dozens of classic and improved decomposition algorithms are integrated inside. The function automatically matches the corresponding kernel according to the input algorithm identifier. Optional extended parameters are supported to adapt to configuration requirements of different algorithms.

Input Parameters:

data: 3D NumPy array with fixed shape [Height, Width, 9] Standard fully polarimetric coherency matrix T, following the unified channel order of this library: data[...,0] = T11 data[...,1] = T22 data[...,2] = T33 data[...,3] = Re(T12) data[...,4] = Re(T13) data[...,5] = Re(T23) data[...,6] = Im(T12) data[...,7] = Im(T13) data[...,8] = Im(T23) Built-in dimension check; exception will be raised if the input is not 3D data with 9 channels.

method: String type, name of decomposition algorithm (case-insensitive) Supported algorithm list:

1. Three-component decomposition freeman_modified, modified_freeman, mfdd, mf3d, f3r freeman_durden, freeman, fdd, f3d dnned, mnned, nned cui, modified_cui, mcui, c3m, cui+hac rsd, mrsd tcd, t3d rsa
2. Four-component decomposition y4d, y4r, g4u psdv1, psdv2
3. Matrix component based decomposition t22_based, t33_based, t11_based t22_based_rsa, t33_based_rsa, t11_based_rsa
4. Other customized decomposition rirsa, ici

**kwargs: Optional keyword arguments Custom configurable parameters for partial algorithms (e.g. deorientation switch). Can be omitted if no extra configuration is needed. Extended parameters only take effect for specific algorithms; no additional parameters are required for general classic algorithms.

Output:

Structured decomposition result in dictionary format with fixed common fields: method: Name of the applied decomposition algorithm General basic output fields: Ps: Surface scattering power Pd: Double-bounce scattering power Pv: Volume scattering power Additional customized fields including polarimetric features, sub-decomposition matrices and angle parameters will be returned according to the selected algorithm.

Import Method:

from polsardp import polsar_decompose

Usage Example:

import numpy as np
from polsardp import polsar_decompose

#Load standard 9-channel fully polarimetric coherency matrix data
T_data = np.load("full_polar_t_matrix.npy")

#Specify decomposition algorithm
method = "RSD"

#Execute fully polarimetric decomposition (no extended parameters)
res = polsar_decompose(T_data, method)
Print basic decomposition results
print("Applied decomposition algorithm:", res["method"])
print("Shape of surface scattering component:", res["Ps"].shape)
print("Shape of double-bounce scattering component:", res["Pd"].shape)

#Example with extended parameters
res2 = polsar_decompose(T_data, "t22_based", deorientation=True)

---

Summary of Supported Decomposition Algorithms:

1. Four-component decomposition

#【1】Classic Yamaguchi four-component polarimetric decomposition
result = polsar_decompose(data, "Y4D")
#【2】Deorientation Yamaguchi four-component polarimetric decomposition
result = polsar_decompose(data, "Y4R")
#【3】G4U four-component polarimetric decomposition
#【4】Polarimetric Symmetry four-component decomposition Version 1
result = polsar_decompose(data, "PSDv1")
#【5】Polarimetric Symmetry four-component decomposition Version 2
result = polsar_decompose(data, "PSDv2")

2. Three-component decomposition

#【6】Classic Freeman-Durden decomposition
result = polsar_decompose(data, "FDD")
#【7】Deorientation-based three-component polarimetric decomposition
result = polsar_decompose(data, "T3D")
#【8】Modified Freeman-Durden decomposition with deorientation
result = polsar_decompose(data, "F3R")
#【9】Classic Non-Negative Eigenvalue Decomposition (NNED)
result = polsar_decompose(data, "NNED")
#【10】Deorientation Non-Negative Eigenvalue Decomposition (DNNED)
result = polsar_decompose(data, "DNNED")
#【11】Model-based three-component decomposition proposed by Yi Cui
result = polsar_decompose(data, "CUI")
#【12】Improved CUI three-component fully polarimetric decomposition
result = polsar_decompose(data, "C3M")
#【13】Improved CUI decomposition combined with helix angle compensation
result = polsar_decompose(data, "CUI+HAC")
#【14】Reflection Symmetry three-component fully polarimetric decomposition
result = polsar_decompose(data, "RSD")
#【15】Three-component decomposition based on T22 component with reflection symmetry approximation
result = polsar_decompose(data, "T22_based", deorientation=True/False)
#【16】Three-component decomposition based on T33 component with reflection symmetry approximation
result = polsar_decompose(data, "T33_based", deorientation=True/False)
#【17】Three-component decomposition based on T11 component with reflection symmetry approximation
result = polsar_decompose(data, "T11_based", deorientation=True/False)

2.1. Three-component decomposition based on reflection symmetry approximation

#【18】Reflection symmetry approximation combined with FDD decomposition
result = polsar_decompose(data, "RSA")
#【19】T22 component based reflection symmetry approximation combined with FDD decomposition
result = polsar_decompose(data, "T22_based_rsa", deorientation=True/False)
#【20】T33 component based reflection symmetry approximation combined with FDD decomposition
result = polsar_decompose(data, "T33_based_rsa", deorientation=True/False)
#【21】T11 component based reflection symmetry approximation combined with FDD decomposition
result = polsar_decompose(data, "T11_based_rsa", deorientation=True/False)
#【22】Rotation-invariant reflection symmetry approximation decomposition (components are mutually independent)
Usage: result = polsar_decompose(data, "ICI")

📌 Recommended priority for algorithm application:

1. Three-component decomposition (1) For input T matrix with sufficient equivalent number of looks ICI: Top recommendation. Complete three-component decomposition; rotation of orientation angle for each component will not affect decomposition results. RSD: Second recommendation. Complete three-component decomposition with prominent double-bounce scattering power. RSA: Third recommendation. (2) For input T matrix with insufficient equivalent number of looks F3R: Simple calculation with good visual performance. DNNED: Second recommendation.

2. Four-component decomposition (1) For input T matrix with sufficient equivalent number of looks PSDv1: Top recommendation. Complete four-component decomposition with fast computation. PSDv2: Second recommendation. Complete four-component decomposition with slightly higher computational complexity. (2) For input T matrix with insufficient equivalent number of looks F4R: Simple calculation with good visual performance.

📌 Other decomposition algorithms are only recommended for comparative research, not for practical application scenarios.

---

Detailed Algorithm Description

【1】Algorithm Name: y4d
Identifier: method="y4d"
Usage: result = polsar_decompose(data, "Y4D")
Introduction: Implementation of classic Yamaguchi four-component polarimetric decomposition
Output (fixed dictionary fields):
Ps: Surface scattering power 
Pd: Double-bounce scattering power 
Pv: Volume scattering power 
Ph: Helix scattering power 
Reference:
Y. Yamaguchi, T. Moriyama, M. Ishido, and H. Yamada, “Four-component 
scattering model for polarimetric SAR image decomposition,” IEEE Trans. 
Geosci. Remote Sens., vol. 43, no. 8, pp. 1699–1706,
Aug. 2005.
==================================================
【2】Algorithm Name: y4r
Identifier: method="y4r"
Usage: result = polsar_decompose(data, "Y4R")
Introduction: Implementation of deorientation Yamaguchi four-component polarimetric decomposition
Output (fixed dictionary fields):
Ps: Surface scattering power 
Pd: Double-bounce scattering power 
Pv: Volume scattering power 
Ph: Helix scattering power 
Reference:
Wentao An, Chunhua Xie, Xinzhe Yuan, Yi Cui, and Jian Yang. “Four-Component 
Decomposition of Polarimetric SAR Images With Deorientation,” IEEE 
Geoscience and Remote Sensing Letters, vol.8, no.6, pp.1090-1094, Nov. 2011.
Note: Deorientation is applied first, followed by Yamaguchi decomposition with non-negative eigenvalue constraints. Only the classic volume scattering model is adopted, the extended volume scattering model based on 2 dB threshold is not used.
==================================================
【3】Algorithm Name: g4u
Identifier: method="g4u"
Usage: result = polsar_decompose(data, "G4U", deorientation=True/False)
Introduction: Implementation of G4U four-component polarimetric decomposition
Output (fixed dictionary fields):
Ps: Surface scattering power 
Pd: Double-bounce scattering power 
Pv: Volume scattering power 
Ph: Helix scattering power 
Optional Parameter:
deorientation: Boolean parameter to enable/disable deorientation (default: False)
Reference:
G. Singh, Y. Yamaguchi, and S.-E. Park, “General four-component scattering power decomposition with unitary transformation of coherency
matrix,” IEEE Trans. Geosci. Remote Sens., vol. 51, no. 5,
pp. 3014–3022, May 2013.
==================================================
【4】Algorithm Name: psdv1
Identifier: method="psdv1"
Usage: result = polsar_decompose(data, "PSDv1")
Introduction: Implementation of Polarimetric Symmetry four-component decomposition Version 1
Output (fixed dictionary fields):
Ps: Surface scattering power 
Pd: Double-bounce scattering power 
Pv: Volume scattering power 
Ph: Helix scattering power 
theta: Twice the orientation angle (unit: radian)
phi: Twice the helix angle (unit: radian)
dataV: Coherency matrix T of volume scattering component
dataPsPd: Coherency matrix T of the second scattering component
dataR: Coherency matrix T of the third scattering component
dataH: Coherency matrix T of helix scattering component
indexH: Pixel mask for pixels adopting the standard helix scattering model
Reference:
Wentao An, and Mingsen Lin. “An Incoherent Decomposition Algorithm Based on Polarimetric Symmetry for Multilook Polarimetric SAR Data,” IEEE Transactions on Geoscience and Remote Sensing, vol.58, no.4, pp. 2383- 2397, Apr. 2020.
==================================================
【5】Algorithm Name: psdv2
Identifier: method="psdv2"
Usage: result = polsar_decompose(data, "PSDv2")
Introduction: Implementation of Polarimetric Symmetry four-component decomposition Version 2
Output (fixed dictionary fields):
Ps: Surface scattering power 
Pd: Double-bounce scattering power 
Pv: Volume scattering power 
Ph: Helix scattering power 
theta: Twice the orientation angle (unit: radian)
phi: Twice the helix angle (unit: radian)
dataV: Coherency matrix T of volume scattering component
dataPsPd: Coherency matrix T of the second scattering component
dataR: Coherency matrix T of the third scattering component
dataH: Coherency matrix T of helix scattering component
indexZ: Boolean matrix with shape [Height,Width,3], indicating pixels adopting standard helix scattering model, extended helix scattering model and invalid helix model respectively.
Reference:
Wentao An, and Mingsen Lin. “An Incoherent Decomposition Algorithm Based on Polarimetric Symmetry for Multilook Polarimetric SAR Data,” IEEE Transactions on Geoscience and Remote Sensing, vol.58, no.4, pp. 2383- 2397, Apr. 2020.
===================== Detailed Algorithm Description =====================
【6】Algorithm Name: freeman_durden / freeman / fdd / f3d
Identifier: method="freeman_durden" or method="freeman" or method="fdd" or method="f3d"
Usage: result = polsar_decompose(data, "FDD")
Introduction: Implementation of classic Freeman-Durden three-component polarimetric decomposition
Output (fixed dictionary fields):
Ps: Surface scattering power 
Pd: Double-bounce scattering power 
Pv: Volume scattering power 
Reference:
A. Freeman and S. L. Durden, “A three-component scattering model for
polarimetric SAR,” IEEE Trans. Geosci. Remote Sens., vol. 36, no. 3,
pp. 963–973, May 1998
===================== Detailed Algorithm Description =====================
【7】Algorithm Name: tcd / t3d
Identifier: method="tcd" or method="t3d"
Usage: result = polsar_decompose(data, "T3D")
Introduction: Implementation of deorientation-based three-component polarimetric decomposition
Output (fixed dictionary fields):
Ps: Surface scattering power 
Pd: Double-bounce scattering power 
Pv: Volume scattering power 
theta: Twice the orientation angle (unit: radian)
Reference:
Wentao An, Yi Cui, Jian Yang. “Three-Component Model-Based Decomposition for Polarimetric SAR Data,” IEEE Transactions on Geoscience and Remote Sensing, vol.48, no.6, pp.2732-2739, June 2010
===================== Detailed Algorithm Description =====================
【8】Algorithm Name: freeman_modified / modified_freeman / mfdd / mf3d / f3r
Identifier: method="freeman_modified" or method="modified_freeman" or method="mfdd" or method="mf3d" or method="f3r"
Usage: result = polsar_decompose(data, "F3R")
Introduction: Implementation of Modified Freeman-Durden three-component polarimetric decomposition
Output (fixed dictionary fields):
Ps: Surface scattering power 
Pd: Double-bounce scattering power 
Pv: Volume scattering power 
phi: Twice the orientation angle
a: a = T11 > 2 * T33
Reference:
Wentao An, Yi Cui, Jian Yang. “Three-Component Model-Based Decomposition for Polarimetric SAR Data,” IEEE Transactions on Geoscience and Remote Sensing, vol.48, no.6, pp.2732-2739, June 2010.
Note: This algorithm replaces the volume scattering model (with polarimetric entropy equal to 1) in the above reference with the classic volume scattering model.
==================================================
【9】Algorithm Name: nned
Identifier: method="nned"
Usage: result = polsar_decompose(data, "NNED")
Introduction: Implementation of classic Non-Negative Eigenvalue Decomposition (NNED)
Output (fixed dictionary fields):
Ps: Surface scattering power 
Pd: Double-bounce scattering power
Pv: Volume scattering power 
remain: Decomposition residual component power
Reference:
J. J. van Zyl, M. Arii, and Y. Kim, “Model-based decomposition of polarimetric SAR covariance matrices constrained for nonnegative eigenvalues,” IEEE Trans. Geosci. Remote Sens., vol. 49, no. 9, pp. 1104–1113, Sep. 2011.
Note: Ps+Pd+Pv+remain = Span
===================== Detailed Algorithm Description =====================
【10】Algorithm Name: dnned / mnned
Identifier: method="dnned" or method="mnned"
Usage: result = polsar_decompose(data, "DNNED")
Introduction: Implementation of deorientation Non-Negative Eigenvalue Decomposition (DNNED)
Output (fixed dictionary fields):
Ps: Surface scattering power 
Pd: Double-bounce scattering power (combined with residual component power)
Pv: Volume scattering power 
remain: Decomposition residual component power
Other internal output parameters of the algorithm
Reference:
(To be published)
Note: This algorithm firstly applies deorientation to T matrix, then performs classic NNED decomposition. All residual power is merged into Pd.
Ps+Pd+Pv = Span
==================================================
【11】Algorithm Name: cui
Identifier: method="cui"
Usage: result = polsar_decompose(data, "CUI")
Introduction: Implementation of model-based three-component fully polarimetric decomposition proposed by Yi Cui
Output (fixed dictionary fields):
Ps: Surface scattering power 
Pd: Double-bounce scattering power 
Pv: Volume scattering power 
theta: Twice the first orientation rotation angle (unit: radian)
phi: Twice the second orientation rotation angle (unit: radian)
dataV: Coherency matrix T of volume scattering component
dataPsPd: Coherency matrix T of the second scattering component
dataR: Coherency matrix T of the third scattering component
Reference:
Y. Cui, Y. Yamaguchi, J. Yang, H. Kobayashi, S.-E. Park, and
G. Singh, “On complete model-based decomposition of polarimetric
SAR coherency matrix data,” IEEE Trans. Geosci. Remote Sens., vol. 52,
no. 4, pp. 1991–2001, Apr. 2014.
Note: This function implements Algorithm 2 proposed in the above literature.
==================================================
【12】Algorithm Name: mcui / modified_cui / c3m
Identifier: method="mcui" or method="modified_cui" or method="c3m"
Usage: result = polsar_decompose(data, "C3M")
Introduction: Implementation of improved CUI three-component fully polarimetric decomposition
Output (fixed dictionary fields):
Ps: Surface scattering power 
Pd: Double-bounce scattering power 
Pv: Volume scattering power 
theta: Twice the first orientation rotation angle (unit: radian)
phi: Twice the second orientation rotation angle (unit: radian)
dataV: Coherency matrix T of volume scattering component
dataPsPd: Coherency matrix T of the second scattering component
dataR: Coherency matrix T of the third scattering component
Reference:
Wentao An, Chunhua Xie. “An Improvement on the Complete Model-Based Decomposition of Polarimetric SAR Data,” IEEE Geoscience and Remote Sensing Letters, vol.11, no.11, pp.1926-1930, Nov. 2014.
==================================================
【13】Algorithm Name: cui+hac
Identifier: method="cui+hac"
Usage: result = polsar_decompose(data, "CUI+HAC")
Introduction: Implementation of improved CUI decomposition combined with helix angle compensation
Output (fixed dictionary fields):
Ps: Surface scattering power 
Pd: Double-bounce scattering power 
Pv: Volume scattering power 
theta: Twice the first orientation rotation angle (unit: radian)
phi: Twice the second orientation rotation angle (unit: radian)
dataV: Coherency matrix T of volume scattering component
dataPsPd: Coherency matrix T of the second scattering component
dataR: Coherency matrix T of the third scattering component
Reference:
(To be published)
Note: The three decomposition components are consistent with C3M algorithm. 
When distinguishing whether the third component belongs to surface 
scattering or volume scattering, the rule T11 < (T22+T33) is adopted to
identify double-bounce scattering, and the rest are identified as surface
scattering, which is equivalent to applying helix angle compensation to the 
third component. Therefore, the proportion of Pd in decomposition results is
higher than that of C3M.
==================================================
【14】Algorithm Name: rsd / mrsd
Identifier: method="rsd" or method="mrsd"
Usage: result = polsar_decompose(data, "RSD")
Introduction: Implementation of Reflection Symmetry three-component fully polarimetric decomposition
Output (fixed dictionary fields):
Ps: Surface scattering power 
Pd: Double-bounce scattering power 
Pv: Volume scattering power 
theta: Twice the orientation angle (unit: radian)
phi: Twice the helix angle (unit: radian)
dataV: Coherency matrix T of volume scattering component
dataPsPd: Coherency matrix T of the second scattering component
dataR: Coherency matrix T of the third scattering component
Reference:
Wentao An, Mingsen Lin, and Haijun Yang, “Modified Reflection Symmetry Decomposition and a New Polarimetric Product of GF-3,” 
IEEE Geoscience and Remote Sensing Letters, Vol. 19, pp. 1-5, Jan. 2022.
Note: This function implements the MRSD decomposition algorithm in the above literature.
==================================================
【15】Algorithm Name: t22_based
Identifier: method="t22_based"
Usage: result = polsar_decompose(data, "T22_based", deorientation=True/False)
Introduction: Implementation of fully polarimetric decomposition based on the T22 channel (deorientation supported)
Output (fixed dictionary fields):
Ps: Surface scattering power 
Pd: Double-bounce scattering power 
Pv: Volume scattering power 
theta: Twice the orientation angle (unit: radian)
phi: Twice the helix angle (unit: radian)
dataV: Coherency matrix T of volume scattering component
dataPsPd: Coherency matrix T of the second scattering component
dataR: Coherency matrix T of the third scattering component
Optional Parameter:
deorientation: Boolean parameter to enable/disable deorientation (default: False, recommended)
Reference:
(To be published)
Note: This algorithm firstly extracts classic volume scattering component, then extracts the second and third components based on the T22 channel.
The deorientation parameter determines whether to apply deorientation to the input T matrix or only to the third component.
Applying deorientation to the input T matrix can slightly improve decomposition performance but increases the complexity of subsequent analysis.
==================================================
【16】Algorithm Name: t33_based
Identifier: method="t33_based"
Usage: result = polsar_decompose(data, "T33_based", deorientation=True/False)
Introduction: Implementation of fully polarimetric decomposition based on the T33 channel (deorientation supported)
Output (fixed dictionary fields):
Ps: Surface scattering power 
Pd: Double-bounce scattering power 
Pv: Volume scattering power 
theta: Twice the orientation angle (unit: radian)
phi: Twice the helix angle (unit: radian)
dataV: Coherency matrix T of volume scattering component
dataPsPd: Coherency matrix T of the second scattering component
dataR: Coherency matrix T of the third scattering component
Optional Parameter:
deorientation: Boolean parameter to enable/disable deorientation (default: False, recommended)
Reference:
(To be published)
Note: This algorithm firstly extracts classic volume scattering component, then extracts the second and third components based on the T33 channel.
The deorientation parameter determines whether to apply deorientation to the input T matrix or only to the third component.
Applying deorientation to the input T matrix can slightly improve decomposition performance but increases the complexity of subsequent analysis.
==================================================
【17】Algorithm Name: t11_based
Identifier: method="t11_based"
Usage: result = polsar_decompose(data, "T11_based", deorientation=True/False)
Introduction: Implementation of fully polarimetric decomposition based on the T11 channel (deorientation supported)
Output (fixed dictionary fields):
Ps: Surface scattering power 
Pd: Double-bounce scattering power 
Pv: Volume scattering power 
theta2: Twice the orientation angle of the second component (unit: radian)
phi2: Twice the helix angle of the second component (unit: radian)
theta3: Twice the orientation angle of the third component (unit: radian)
phi3: Twice the helix angle of the third component (unit: radian)
dataV: Coherency matrix T of volume scattering component
dataPsPd: Coherency matrix T of the second scattering component
dataR: Coherency matrix T of the third scattering component
Optional Parameter:
deorientation: Boolean parameter to enable/disable deorientation (default: False, recommended)
Reference:
(To be published)
Note: This algorithm firstly extracts classic volume scattering component, then extracts the second and third components based on the T11 channel.
The deorientation parameter determines whether to apply deorientation to the input T matrix or only to the second and third components.
deorientation=False is recommended.
==================================================
【18】Algorithm Name: rsa
Identifier: method="rsa"
Usage: result = polsar_decompose(data, "RSA")
Introduction: Three-component decomposition combining reflection symmetry approximation and FDD
Output (fixed dictionary fields):
Ps: Surface scattering power 
Pd: Double-bounce scattering power 
Pv: Volume scattering power 
theta: Twice the orientation angle (unit: radian)
phi: Twice the helix angle (unit: radian)
dataV: Coherency matrix T of volume scattering component
dataPsPd: Coherency matrix T of the second scattering component
dataR: Coherency matrix T of the third scattering component
Reference:
Wentao An, and Mingsen Lin. “A Reflection Symmetry Approximation of Multilook Polarimetric SAR Data and its Application to Freeman-Durden Decomposition,” 
IEEE Transactions on Geoscience and Remote Sensing, vol.57, no.6, pp. 3649-3660, Jun. 2019.
==================================================
【19】Algorithm Name: t22_based_rsa
Identifier: method="t22_based_rsa"
Usage: result = polsar_decompose(data, "T22_based_rsa", deorientation=True/False)
Introduction: implementation of a three-component polarimetric decomposition algorithm combining FDD and the reflection symmetry approximation obtained via the T22-based decomposition 
Output (fixed dictionary fields):
Ps: Surface scattering power 
Pd: Double-bounce scattering power 
Pv: Volume scattering power 
theta: Twice the orientation angle (unit: radian)
phi: Twice the helix angle (unit: radian)
dataV: Coherency matrix T of volume scattering component
dataPsPd: Coherency matrix T of the second scattering component
dataR: Coherency matrix T of the third scattering component
Optional Parameter:
deorientation: Boolean parameter to enable/disable deorientation (default: False, recommended)
Reference:
(To be published)
Note: This algorithm firstly extracts classic volume scattering component, then extracts the second and third components based on the T22 channel.
The deorientation parameter determines whether to apply deorientation to the input T matrix or only to the third component.
Applying deorientation to the input T matrix can slightly improve decomposition performance but increases the complexity of subsequent analysis.
Reflection symmetry approximation is obtained by summing the three components, followed by classic Freeman-Durden decomposition.
==================================================
【20】Algorithm Name: t33_based_rsa
Identifier: method="t33_based_rsa"
Usage: result = polsar_decompose(data, "T33_based_rsa", deorientation=True/False)
Introduction: implementation of a three-component polarimetric decomposition algorithm combining FDD and the reflection symmetry approximation obtained via the T33-based decomposition 
Output (fixed dictionary fields):
Ps: Surface scattering power 
Pd: Double-bounce scattering power 
Pv: Volume scattering power 
theta: Twice the orientation angle (unit: radian)
phi: Twice the helix angle (unit: radian)
dataV: Coherency matrix T of volume scattering component
dataPsPd: Coherency matrix T of the second scattering component
dataR: Coherency matrix T of the third scattering component
Optional Parameter:
deorientation: Boolean parameter to enable/disable deorientation (default: False, recommended)
Reference:
(To be published)
Note: This algorithm firstly extracts classic volume scattering component, then extracts the second and third components based on the T33 channel.
The deorientation parameter determines whether to apply deorientation to the input T matrix or only to the third component.
Applying deorientation to the input T matrix can slightly improve decomposition performance but increases the complexity of subsequent analysis.
Reflection symmetry approximation is obtained by summing the three components, followed by classic Freeman-Durden decomposition.
==================================================
【21】Algorithm Name: t11_based_rsa
Identifier: method="t11_based_rsa"
Usage: result = polsar_decompose(data, "T11_based_rsa", deorientation=True/False)
Introduction: implementation of a three-component polarimetric decomposition algorithm combining FDD and the reflection symmetry approximation obtained via the T11-based decomposition 
Output (fixed dictionary fields):
Ps: Surface scattering power 
Pd: Double-bounce scattering power 
Pv: Volume scattering power 
theta2: Twice the orientation angle of the second component (unit: radian)
phi2: Twice the helix angle of the second component (unit: radian)
theta3: Twice the orientation angle of the third component (unit: radian)
phi3: Twice the helix angle of the third component (unit: radian)
dataV: Coherency matrix T of volume scattering component
dataPsPd: Coherency matrix T of the second scattering component
dataR: Coherency matrix T of the third scattering component
Optional Parameter:
deorientation: Boolean parameter to enable/disable deorientation (default: False)
Reference:
(To be published)
Note: This algorithm firstly extracts classic volume scattering component, then extracts the second and third components based on the T11 channel.
The deorientation parameter determines whether to apply deorientation to the input T matrix or only to the second and third components.
deorientation=False is recommended.
Reflection symmetry approximation is obtained by summing the three components, followed by classic Freeman-Durden decomposition.
==================================================
【22】Algorithm Name: rirsa / ici
Identifier: method="rirsa" or method="ici"
Usage: result = polsar_decompose(data, "ICI")
Introduction: Rotation-invariant reflection symmetry approximation decomposition (components are mutually independent)
Output (fixed dictionary fields):
Ps: Surface scattering power 
Pd: Double-bounce scattering power 
Pv: Volume scattering power 
theta2: Twice the orientation angle of the second component (unit: degree)
phi2: Twice the helix angle of the second component (unit: degree)
theta3: Twice the orientation angle of the third component (unit: degree)
phi3: Twice the helix angle of the third component (unit: degree)
x: max(T11,T22)/(T11+T22) of the second component
omega: angle(T12) of the second component
theta1: Twice the orientation angle of the first component (unit: degree)
phi1: Twice the helix angle of the first component (unit: degree)
Reference:
(To be published)
Note: The original polarimetric coherency matrix T can be fully reconstructed based on output results.
Either group of (x, omega) or (theta1, phi1) is sufficient for reconstruction.

---

compact_decompose - Main Entry for Compact Polarimetric Decomposition

Function: Unified main entry for incoherent decomposition of compact polarimetric SAR data. Multiple mainstream compact polarimetric decomposition algorithms are integrated, and the corresponding kernel will be invoked automatically according to the input algorithm name.

Input Parameters:

g0: 2D NumPy array, the first component of compact polarimetric Stokes vector g1: 2D NumPy array, the second component of compact polarimetric Stokes vector g2: 2D NumPy array, the third component of compact polarimetric Stokes vector g3: 2D NumPy array, the fourth component of compact polarimetric Stokes vector

indexRL: Integer, compact polarimetric mode, only 2 or 3 is supported 2 - Right-hand circular polarization transmission + linear polarization reception (RH RV) 3 - Left-hand circular polarization transmission + linear polarization reception (LH LV)

method: String type, name of decomposition algorithm (case-insensitive) Supported algorithm list: m_delta, m_chi, ak, dey, wang, hou m_alpha, malpha mmalpha, mma C3D MC3D

**kwargs: Optional extended parameters (dynamically passed according to requirements of different algorithms)

Output:

Decomposition result in dictionary format with fixed fields: method: Name of the applied decomposition algorithm Scattering power components will be returned automatically according to algorithm type: Ps: Surface scattering power Pd: Double-bounce scattering power Pv: Volume scattering power Custom parameters exclusive to each algorithm will also be included.

Import Method:

from polsardp import compact_decompose

Usage Example:

import numpy as np
from polsardp import compact_decompose

#Load compact polarimetric Stokes vector data
g0 = np.load("g0.npy")
g1 = np.load("g1.npy")
g2 = np.load("g2.npy")
g3 = np.load("g3.npy")

#Set core parameters
indexRL = 2
method = "mma" # Replace with any supported algorithm

#Execute compact polarimetric decomposition
result = compact_decompose(g0, g1, g2, g3, indexRL, method)
#Print decomposition information
print("Decomposition algorithm:", result["method"])
if "Ps" in result:
    print("Shape of surface scattering power:", result["Ps"].shape)

---

List of Supported Algorithms:

    m_alpha, malpha
    mmalpha, mma
    C3D
    MC3D
    m_delta, m_chi, ak, dey, wang, hou
📌 Recommended priority for algorithm application: C3D, mma, m_alpha
📌 The above three algorithms support full reconstruction of input 
    data, with decomposition performance decreasing in turn.
📌 Other compact polarimetric decomposition algorithms are not
    recommended for practical application.

---

【1】Algorithm Name: m_alpha / malpha
Identifier: method="m_alpha" or method="malpha"
Usage: result = compact_decompose(g0, g1, g2, g3, indexRL, "m_alpha")
Introduction: Classic m-alpha compact polarimetric decomposition
Output (fixed dictionary fields):
Ps: Surface scattering power 
Pd: Double-bounce scattering power 
Pv: Volume scattering power 
alpha: Polarimetric alpha angle
m: Degree of polarization
phi: atan2(g2,g1) if indexRL==2; atan2(-g2,g1) if index == 3; unit: degree
	Retained for reconstructing the original Stokes vector from decomposition results.
Reference:
Wentao An, Yarong Zou and Qian Feng, “A Modified Incoherent Compact 
Polarimetric Decomposition Algorithm,” IEEE Transactions on Geoscience and 
Remote Sensing, vol. 63, pp. 1-13, 2025, Art no. 5205713, doi: 10.1109/TGRS.
2025.3545022
==================================================
【2】Algorithm Name: mmalpha / mma
Identifier: method="mmalpha" or method="mma"
Usage: result = compact_decompose(g0, g1, g2, g3, indexRL, "mmalpha")
Introduction: modified m-alpha compact polarimetric decomposition
Output (fixed dictionary fields):
Ps: Surface scattering power 
Pd: Double-bounce scattering power 
Pv: Volume scattering power 
alpha: Polarimetric alpha angle
m: Degree of polarization
phi: atan2(g2,g1) if indexRL==2; atan2(-g2,g1) if indexRL == 3; unit: degree
Retained for reconstructing the original Stokes vector from decomposition results.
Reference:
Wentao An, Yarong Zou and Qian Feng, “A Modified Incoherent Compact 
Polarimetric Decomposition Algorithm,” IEEE Transactions on Geoscience and 
Remote Sensing, vol. 63, pp. 1-13, 2025, Art no. 5205713, doi: 10.1109/TGRS.
2025.3545022
==================================================
【3】Algorithm Name: C3D
Identifier: method="C3D"
Usage: result = compact_decompose(g0, g1, g2, g3, indexRL, "C3D")
Introduction: C3D compact polarimetric decomposition (not published, top recommendation)
Output (fixed dictionary fields):
result['Ps']: Surface scattering power 
result['Pd']: Double-bounce scattering power 
result['Pv']: Volume scattering power 
result['phi']:atan2(g2,g1) if indexRL==2; atan2(-g2,g1) if indexRL == 3;
	     unit: degree
Reference:
(To be published)
Note: The original Stokes vector can be fully reconstructed based on output 
Ps, Pd, Pv and phi. Reconstruction function will be supplemented in 
subsequent versions.
==================================================
【4】Algorithm Name: MC3D
Identifier: method="MC3D"
Usage: result = compact_decompose(g0, g1, g2, g3, indexRL, "MC3D")
Introduction: Improved C3D compact polarimetric decomposition (not published)
Output (fixed dictionary fields):
result['Ps']: Surface scattering power 
result['Pd']: Double-bounce scattering power 
result['Pv']: Volume scattering power 
Reference:
(To be published)
Note: Optimized decomposition results for regions dominated by surface scattering.
==================================================
【5】Algorithm Name: m_delta / m_chi / ak / dey / wang / hou
Identifier: method="m_delta" / "m_chi" / "ak" / "dey" / "wang" / "hou"
Usage: result = compact_decompose(g0, g1, g2, g3, indexRL, "Dey")
Algorithm Description: A collection of classic compact polarimetric 
decomposition algorithms. A single function call calculates results of all 
six algorithms simultaneously and outputs independent scattering power 
components.

Output (fixed dictionary fields):
Ps_delta: Surface scattering power from m_delta decomposition
Pd_delta: Double-bounce scattering power from m_delta decomposition
Pv_delta: Volume scattering power from m_delta decomposition
Ps_chi: Surface scattering power from m_chi decomposition
Pd_chi: Double-bounce scattering power from m_chi decomposition
Pv_chi: Volume scattering power from m_chi decomposition
Ps_AK: Surface scattering power from A.K. decomposition
Pd_AK: Double-bounce scattering power from A.K. decomposition
Pv_AK: Volume scattering power from A.K. decomposition
Ps_Dey: Surface scattering power from Dey decomposition
Pd_Dey: Double-bounce scattering power from Dey decomposition
Pv_Dey: Volume scattering power from Dey decomposition
Ps_Wang: Surface scattering power from Wang decomposition
Pd_Wang: Double-bounce scattering power from Wang decomposition
Pv_Wang: Volume scattering power from Wang decomposition
Ps_Hou: Surface scattering power from Hou decomposition
Pd_Hou: Double-bounce scattering power from Hou decomposition
Pv_Hou: Volume scattering power from Hou decomposition
Remarks:
All six algorithms are computed automatically in one call with separate output fields.
Wang decomposition and Hou decomposition only support indexRL = 2, and no 
outputs will be generated when indexRL=3.
References:
Wentao An, Yarong Zou and Qian Feng, “A Modified Incoherent Compact Polarimetric Decomposition Algorithm,” 
IEEE Transactions on Geoscience and Remote Sensing, 
vol. 63, pp. 1-13, 2025, Art no. 5205713, 
doi: 10.1109/TGRS.2025.3545022

---

f_RIRSA_Inv0 - RIRSA Inverse Decomposition & Reconstruction Function

Function: Perform inverse decomposition based on RIRSA (also known as ICI) polarimetric decomposition results, and reconstruct the fully polarimetric SAR coherency matrix T from the decomposition outputs. This function supports dual input modes. It automatically completes angle rotation correction and superposition of scattering components, and returns the reconstructed standard coherency matrix as well as each individual sub-scattering component.

Input Parameters:

varargin: Variable input arguments Mandatory 1st argument: outParameters (dictionary type), the complete set of feature parameters output by the RIRSA (ICI) decomposition. Optional 2nd argument: Extended parameter for angle-mode reconstruction. The x/omega mode is used by default if this argument is omitted. All output matrices are newly created arrays, and the original input data will not be modified.

Output:

dataInv: Reconstructed fully polarimetric coherency matrix (3D array, HW9, standard channel format) dataV: Coherency matrix of volume scattering component (3D array, HW9) data2: Coherency matrix of the second component (3D array, HW9) dataR: Coherency matrix of the third component (3D array, HW9) All output matrices follow the unified channel specification of this library: data[...,0] = T11 data[...,1] = T22 data[...,2] = T33 data[...,3] = Re(T12) data[...,4] = Re(T13) data[...,5] = Re(T23) data[...,6] = Im(T12) data[...,7] = Im(T13) data[...,8] = Im(T23)

Import Method:

from polsardp import f_RIRSA_Inv0

Usage Example:

import numpy as np
from polsardp import f_RIRSA_Inv0

#Load parameter dictionary output by ICI decomposition
outParameters = polsar_decompose(Your_T_matrix_data, "ICI")

#Execute RIRSA inverse decomposition (default mode)
dataInv, dataV, data2, dataR = f_RIRSA_Inv0(outParameters)
#Print output result
print(np.max(np.abs(dataInv-Your_T_matrix_data)))

---

fSpanImShow0 - RGB Visualization Function for Polarimetric Decomposition Results

Function: Render RGB visualization for fully polarimetric SAR decomposition results, and display polarimetric power and amplitude images. Images are displayed with a specified power threshold to ensure consistent display standards across multiple scenes.

This function accepts 1 ~ 5 variable input arguments, automatically completes data preprocessing, brightness normalization and channel mapping, generates standard RGB images and displays figures.

Input Parameters:

varargin: Variable input arguments (1 to 5 arguments are supported for flexible application) Parameter description:

1. argument: data (polarimetric coherency matrix data). Only data[:,:,0:3] will be displayed, and the output is a power image.
2. arguments: data, tempMean (polarimetric coherency matrix T + brightness threshold adjustment parameter), output is a power image.
3. arguments: data, tempMean, [ ] (scattering channel data + brightness threshold adjustment parameter). The empty third argument indicates displaying amplitude images.
4. arguments: Ps, Pd, Pv, tempMean (three scattering power components + brightness threshold adjustment parameter), output is a power image.
5. arguments: Ps, Pd, Pv, tempMean, [ ] (three scattering power components + brightness threshold adjustment parameter). The empty fifth argument indicates displaying amplitude images.

Note: tempMean: Brightness adjustment parameter, default value: -6.0

Output:

z: Normalized RGB visualization image (3D NumPy array with shape (Height, Width, 3)). Values are automatically clipped to the range [0, 1] with standard RGB channel order. The function automatically creates and displays figure windows without modifying the original input data.

📌 tempMean of fSpanImShow0 acts as the brightness threshold, which is essentially an average power value. When multiple images are displayed with the same power threshold, the image brightness directly reflects the relative power magnitude. A unified display threshold ensures visual comparability among different results. 📌 Figures are rendered inside the function. To view images, import matplotlib and run plt.show():

import matplotlib.pyplot as plt
plt.show()

Import Method:

from polsardp import fSpanImShow0

Usage Example:

import numpy as np
import matplotlib.pyplot as plt
from polsardp import fSpanImShow0

#Example 1: Basic call (input 3-channel scattering data)
data = np.load("polarimetric_decompose_result.npy")
rgb_image = fSpanImShow0(data)

#Example 2: Call with brightness parameter
rgb_image = fSpanImShow0(data, -5.0, [])

#Example 3: Visualization for Ps/Pd/Pv three components (most commonly used)
Ps = np.load("Ps.npy")
Pd = np.load("Pd.npy")
Pv = np.load("Pv.npy")
rgb_image = fSpanImShow0(Ps, Pd, Pv, 6.0,[])
plt.show()
#Print shape of output RGB image
print("Shape of visualization RGB image:", rgb_image.shape)

---

fSpanImShow2 - Adaptive RGB Visualization Function for Polarimetric Decomposition Results

Function: Perform adaptive RGB rendering and display for fully polarimetric SAR decomposition results, including polarimetric power and amplitude images. The display threshold is automatically calculated based on input data, achieving optimal visual effect for single scenes, while thresholds are inconsistent across different scenes.

This function accepts 1 ~ 5 variable input arguments, automatically completes data preprocessing, adaptive brightness normalization and channel mapping, generates standard RGB images and displays figures.

Input Parameters:

varargin: Variable input arguments (1 to 5 arguments are supported for flexible application) Parameter description:

1. argument: data (3-channel polarimetric coherency matrix data). Only data[:,:,0:3] will be displayed, and the output is a power image.
2. arguments: data, n (3-channel scattering data + brightness adjustment parameter), output is a power image.
3. arguments: data, n, [ ] (3-channel scattering data + brightness adjustment parameter). The empty third argument indicates displaying amplitude images.
4. arguments: Ps, Pd, Pv, n (three scattering power components + brightness adjustment parameter), output is a power image.
5. arguments: Ps, Pd, Pv, n, [ ] (three scattering power components + brightness adjustment parameter). The empty fifth argument indicates displaying amplitude images. n: Normalization mode parameter n=1: Bright image n=0: Moderate brightness n=-1: Dark image

Output:

z: Normalized RGB visualization image (3D NumPy array with shape (3, Height, Width)) z1: Image array adapted for matplotlib display (shape (Height, Width, 3)) Values are automatically clipped to the range [0, 1], and the channel order is consistent with MATLAB.

📌 Figures are rendered inside the function. To view images, import matplotlib and run plt.show():

import matplotlib.pyplot as plt
plt.show()

Import Method:

from polsardp import fSpanImShow2

Usage Example:

import numpy as np
import matplotlib.pyplot as plt
from polsardp import fSpanImShow2

#Example 1: Basic call (input 3-channel scattering data)
data = np.load("polarimetric_decompose_result.npy")
rgb_image = fSpanImShow2(data)

#Example 2: Call with normalization mode
rgb_image = fSpanImShow2(data, 1,[])

#Example 3: Visualization for Ps/Pd/Pv three components (most commonly used)
Ps = np.load("Ps.npy")
Pd = np.load("Pd.npy")
Pv = np.load("Pv.npy")
rgb_image = fSpanImShow2(Ps, Pd, Pv, -1,[])
plt.show()
#Print shape of output RGB image
print("Shape of visualization RGB image:", rgb_image.shape)

---

---

The above functions are added in Version V0.0.1. The following functions are added in Version V0.0.2 and V0.0.3. Note: These minor versions are internal development records and have not been officially released.

---

---

fk2T - Convert Pauli Vector k to Coherency Matrix T

Function: Convert polarimetric Pauli vector k (3 complex channels t1, t2, t3) to fully polarimetric SAR coherency matrix T. The calculation of complex conjugate, modulus square, real and imaginary parts strictly follows standard SAR polarimetric definitions, and is fully consistent with the original MATLAB function. k denotes the transpose of [t1,t2,t3]

Input Parameters (3 arguments):

t1: 2D complex NumPy array with shape [Height, Width], the first channel of Pauli vector t2: 2D complex NumPy array with shape [Height, Width], the second channel of Pauli vector t3: 2D complex NumPy array with shape [Height, Width], the third channel of Pauli vector

Output:

T: 3D NumPy array with shape [Height, Width, 9], standard polarimetric coherency matrix Channel order: T[...,0] = T11 = |t1|² T[...,1] = T22 = |t2|² T[...,2] = T33 = |t3|² T[...,3] = Re(t1·t2*) T[...,4] = Re(t1·t3*) T[...,5] = Re(t2·t3*) T[...,6] = Im(t1·t2*) T[...,7] = Im(t1·t3*) T[...,8] = Im(t2·t3*)

Import Method:

from polsardp import fk2T

Usage Example:

import numpy as np
from polsardp import fk2T

#Generate test complex Pauli vector (2x2)
t1 = np.array([[1+2j, 3+4j], [5+6j, 7+8j]])
t2 = np.array([[9+10j,11+12j],[13+14j,15+16j]])
t3 = np.array([[17+18j,19+20j],[21+22j,23+24j]])

#Convert to coherency matrix T
T = fk2T(t1, t2, t3)
#Print output shape
print("Shape of T matrix:", T.shape)

---

fS2T - Convert Scattering Matrix S to Coherency Matrix T

Function: Convert fully polarimetric SAR scattering matrix S (HH/HV/VH/VV) to Pauli vector k, and further generate standard polarimetric coherency matrix T. The workflow and definitions fully comply with official SAR polarimetric standards. k denotes the transpose of [t1,t2,t3], which is derived from scattering matrix S via polarimetric basis transformation.

Input Parameters (1 argument):

data: Custom data object containing four 2D complex NumPy arrays data.HH: Complex array with shape [Height, Width], horizontal transmit & horizontal receive channel data.HV: Complex array with shape [Height, Width], horizontal transmit & vertical receive channel data.VH: Complex array with shape [Height, Width], vertical transmit & horizontal receive channel data.VV: Complex array with shape [Height, Width], vertical transmit & vertical receive channel

Output:

T: 3D NumPy array with shape [Height, Width, 9], standard polarimetric coherency matrix Channel order: T[...,0] = T11 = |t1|² T[...,1] = T22 = |t2|² T[...,2] = T33 = |t3|² T[...,3] = Re(t1·t2*) T[...,4] = Re(t1·t3*) T[...,5] = Re(t2·t3*) T[...,6] = Im(t1·t2*) T[...,7] = Im(t1·t3*) T[...,8] = Im(t2·t3*) Where: t1 = (HH + VV) / √2 t2 = (HH - VV) / √2 t3 = (HV + VH) / √2

Import Method:

from polsardp import fS2T

Usage Example:

import numpy as np
from polsardp import fS2T

#Define data class
class GPS:
	pass

#Construct test data
data = GPS()
data.HH = np.random.rand(2, 3) + 1j * np.random.rand(2, 3)
data.HV = np.random.rand(2, 3) + 1j * np.random.rand(2, 3)
data.VH = np.random.rand(2, 3) + 1j * np.random.rand(2, 3)
data.VV = np.random.rand(2, 3) + 1j * np.random.rand(2, 3)

#Convert to coherency matrix T
T = fS2T(data)

#Print output shape
print("Shape of T matrix:", T.shape)

---

fT2C - Convert Coherency Matrix T to Covariance Matrix C

Function: Convert fully polarimetric SAR coherency matrix T to standard polarimetric covariance matrix C. Channel transformation, coefficient calculation and assignment of real/imaginary parts strictly follow official SAR polarimetric definitions, consistent with the original MATLAB function.

Input Parameters (1 argument):

T: 3D NumPy array with shape [Height, Width, 9], standard polarimetric coherency matrix

Output:

C: 3D NumPy array with shape [Height, Width, 9], standard polarimetric covariance matrix

Channel order: T[...,0] = T11 T[...,1] = T22 T[...,2] = T33 T[...,3] = Re(T12) T[...,4] = Re(T13) T[...,5] = Re(T23) T[...,6] = Im(T12) T[...,7] = Im(T13) T[...,8] = Im(T23)

C[...,0] = C11 C[...,1] = C22 C[...,2] = C33 C[...,3] = Re(C12) C[...,4] = Re(C13) C[...,5] = Re(C23) C[...,6] = Im(C12) C[...,7] = Im(C13) C[...,8] = Im(C23)

Import Method:

from polsardp import fT2C

Usage Example:

import numpy as np
from polsardp import fT2C

#Generate test coherency matrix T (5x5x9)
T = np.random.rand(5, 5, 9).astype(np.float64)

#Convert to covariance matrix C
C = fT2C(T)
#Print output shape
print("Shape of C matrix:", C.shape)

---

fC2T - Convert Covariance Matrix C to Coherency Matrix T

Function: Convert fully polarimetric SAR covariance matrix C to standard polarimetric coherency matrix T. Channel transformation, coefficient calculation and assignment of real/imaginary parts strictly follow official SAR polarimetric definitions.

Input Parameters (1 argument):

C: 3D NumPy array with shape [Height, Width, 9], standard polarimetric covariance matrix

Output:

T: 3D NumPy array with shape [Height, Width, 9], standard polarimetric coherency matrix

Channel order: T[...,0] = T11 T[...,1] = T22 T[...,2] = T33 T[...,3] = Re(T12) T[...,4] = Re(T13) T[...,5] = Re(T23) T[...,6] = Im(T12) T[...,7] = Im(T13) T[...,8] = Im(T23)

C[...,0] = C11 C[...,1] = C22 C[...,2] = C33 C[...,3] = Re(C12) C[...,4] = Re(C13) C[...,5] = Re(C23) C[...,6] = Im(C12) C[...,7] = Im(C13) C[...,8] = Im(C23)

Import Method:

from polsardp import fC2T

Usage Example:

import numpy as np
from polsardp import fC2T

#Generate test covariance matrix C (2x3x9)
C = np.random.rand(2, 3, 9).astype(np.float64)

#Convert to coherency matrix T
T = fC2T(C)
#Print output shape
print("Shape of T matrix:", T.shape)

======================================================================

T2K - Convert Coherency Matrix T to Kennaugh Matrix K

Function: Convert fully polarimetric SAR coherency matrix T to standard polarimetric Kennaugh matrix K.

Input Parameters (1 argument):

T: 3D NumPy array with shape [Height, Width, 9], standard polarimetric coherency matrix

Channel order: T[...,0] = T11; T[...,1] = T22; T[...,2] = T33; T[...,3] = Re(T12); T[...,4] = Re(T13); T[...,5] = Re(T23); T[...,6] = Im(T12); T[...,7] = Im(T13); T[...,8] = Im(T23);

Output:

K: 3D NumPy array with shape [Height, Width, 9], standard polarimetric Kennaugh matrix

Channel order: K[...,0] = K11; K[...,1] = K12; K[...,2] = K13; K[...,3] = K14; K[...,4] = K22; K[...,5] = K23; K[...,6] = K24; K[...,7] = K33; K[...,8] = K34;

Import Method:

from polsardp import T2K

Usage Example:

import numpy as np
from polsardp import T2K

#Generate test coherency matrix T (5x5x9)
T = np.random.rand(5, 5, 9).astype(np.float64)

#Convert to Kennaugh matrix K
K = T2K(T)
#Print output shape
print("Shape of K matrix:", K.shape)

---

K2T - Convert Kennaugh Matrix K to Coherency Matrix T

Function: Convert fully polarimetric SAR Kennaugh matrix K to standard polarimetric coherency matrix T. Correspondence with Mueller matrix: M = np.diag([1,1,1,-1]) @ K

Input Parameters (1 argument):

K: 3D NumPy array with shape [Height, Width, 9], standard polarimetric Kennaugh matrix Channel order: K[...,0] = K11; K[...,1] = K12; K[...,2] = K13; K[...,3] = K14; K[...,4] = K22; K[...,5] = K23; K[...,6] = K24; K[...,7] = K33; K[...,8] = K34;

Output:

T: 3D NumPy array with shape [Height, Width, 9], standard polarimetric coherency matrix Channel order: T[...,0] = T11; T[...,1] = T22; T[...,2] = T33; T[...,3] = Re(T12); T[...,4] = Re(T13); T[...,5] = Re(T23); T[...,6] = Im(T12); T[...,7] = Im(T13); T[...,8] = Im(T23);

Import Method:

from polsardp import K2T

Usage Example:

import numpy as np
from polsardp import K2T

#Generate test Kennaugh matrix K (5x5x9)
K = np.random.rand(5, 5, 9).astype(np.float64)

#Convert to coherency matrix T
T = K2T(K)
#Print output shape
print("Shape of T matrix:", T.shape)

---

fT2G - Convert Coherency Matrix T to Compact Polarimetric Stokes Vector g

Function: Convert fully polarimetric SAR coherency matrix T to Stokes vector g under compact polarimetric mode (6 optional modes).

Input Parameters (2 arguments):

T: 3D NumPy array with shape [Height, Width, 9] Channel order: T[...,0] = T11 T[...,1] = T22 T[...,2] = T33 T[...,3] = Re(T12) T[...,4] = Re(T13) T[...,5] = Re(T23) T[...,6] = Im(T12) T[...,7] = Im(T13) T[...,8] = Im(T23)

mode: Code for compact polarimetric mode (0 ~ 5) 0 - RH-RR: Right-hand circular polarization transmit, circular polarization receive 1 - LH-LL: Left-hand circular polarization transmit, circular polarization receive 2 - RH-RV: Right-hand circular polarization transmit, linear polarization receive 3 - LH-LV: Left-hand circular polarization transmit, linear polarization receive 4 - [1;1] H V: 45° linear polarization transmit, linear polarization receive 5 - [1;-1] H V: -45° linear polarization transmit, linear polarization receive

Output:

g0, g1, g2, g3: Four independent components of compact polarimetric Stokes vector g

Import Method:

from polsardp import fT2G

Usage Example:

import numpy as np
from polsardp import fT2G

#Load fully polarimetric T matrix data
T_matrix = np.random.rand(5, 5, 9).astype(np.float64)

#Set compact polarimetric mode
mode = 2

#Convert to Stokes vector g
g0, g1, g2, g3 = fT2G(T_matrix, mode)

#Print output shape
print(g0.shape, g1.shape, g2.shape, g3.shape)

---

fCalHalpha - H-alpha Polarimetric Decomposition

Function: Perform H-alpha decomposition on fully polarimetric SAR coherency matrix T, and calculate two core polarimetric features: polarimetric entropy H and polarimetric alpha angle. Note: This function calculates H and alpha via pixel-wise eigenvalue decomposition, which requires relatively long computation time.

Input Parameters (1 argument):

preT: 3D NumPy array with shape [Height, Width, 9] Channel order: preT[...,0] = T11 preT[...,1] = T22 preT[...,2] = T33 preT[...,3] = Re(T12) preT[...,4] = Re(T13) preT[...,5] = Re(T23) preT[...,6] = Im(T12) preT[...,7] = Im(T13) preT[...,8] = Im(T23)

Output:

H: Polarimetric entropy (2D NumPy array, shape [Height, Width]), value range [0, 1] alpha: Mean alpha angle (2D NumPy array, shape [Height, Width]), value range [0°, 90°]

Import Method:

from polsardp import fCalHalpha

Usage Example:

import numpy as np
from polsardp import fCalHalpha

#Load fully polarimetric T matrix data
T_matrix = np.random.rand(5, 5, 9).astype(np.float64)

#Calculate H-alpha features
H, alpha = fCalHalpha(T_matrix)

#Print output shape
print(H.shape, alpha.shape)

References: S. R. Cloude and E. Pottier, “An entropy based classification scheme for land applications of polarimetric SAR,” IEEE Trans. Geosci. Remote Sens., vol. 35, no. 1, pp. 68–78, Jan. 1997.

---

fCalHq - Calculate Polarimetric H-q Parameters

Function: Calculate two core polarimetric features (polarimetric entropy H and parameter q) based on fully polarimetric SAR coherency matrix T. Note: Polarimetric entropy H is computed via a fast algorithm based on cubic polynomial decomposition for high efficiency.

Input Parameters (1 argument):

data: 3D NumPy array with shape [Height, Width, 9] Channel order: data[...,0] = T11 data[...,1] = T22 data[...,2] = T33 data[...,3] = Re(T12) data[...,4] = Re(T13) data[...,5] = Re(T23) data[...,6] = Im(T12) data[...,7] = Im(T13) data[...,8] = Im(T23)

Output:

H: Polarimetric entropy (2D NumPy array, shape [Height, Width]), value range [0, 1] q: Polarimetric q parameter (2D NumPy array, shape [Height, Width]), value range [0, 1]

Import Method:

from polsardp import fCalHq

#Usage Example:

import numpy as np
from polsardp import fCalHq

#Load fully polarimetric T matrix data
T_matrix = np.random.rand(5, 5, 9).astype(np.float64)

#Calculate H-q parameters
H, q = fCalHq(T_matrix)
#Print output shape
print(H.shape, q.shape)

References: Wentao AN, Yi Cui, Jian Yang, Hongji Zhang. “Fast Alternatives to H/α for Polarimetric SAR,” IEEE Geoscience and Remote Sensing Letters, vol.7, no.2, pp.343-347, April 2010. 📌 Note: The q parameter implemented here is defined as q=1-T11/Span, which is slightly different from q=T11/Span in the above reference. This function mainly implements the fast calculation of polarimetric entropy H via analytical solution of cubic equations described in the literature.

---

fCal_hq - Calculate Polarimetric h and q Parameters

Function: Calculate two polarimetric features (parameter h and parameter q) based on fully polarimetric SAR coherency matrix T.

Input Parameters (1 argument):

data: 3D NumPy array with shape [Height, Width, 9] Channel order: data[...,0] = T11 data[...,1] = T22 data[...,2] = T33 data[...,3] = Re(T12) data[...,4] = Re(T13) data[...,5] = Re(T23) data[...,6] = Im(T12) data[...,7] = Im(T13) data[...,8] = Im(T23)

Output:

h: Polarimetric h parameter (2D NumPy array, shape [Height, Width]) q: Polarimetric q parameter (2D NumPy array, shape [Height, Width]), value range [0, 1]

Import Method:

from polsardp import fCal_hq

Usage Example:

import numpy as np
from polsardp import fCal_hq

#Load fully polarimetric T matrix data
T_matrix = np.random.rand(5, 5, 9).astype(np.float64)
Calculate h-q parameters
h, q = fCal_hq(T_matrix)
Print output shape
print(h.shape, q.shape)

References: Wentao AN, Yi Cui, Jian Yang, Hongji Zhang. “Fast Alternatives to H/α for Polarimetric SAR,” IEEE Geoscience and Remote Sensing Letters, vol.7, no.2, pp.343-347, April 2010.

📌 Note: The q parameter implemented here is defined as q=1-T11/Span, which is slightly different from q=T11/Span in the above reference.

---

---