Model Free 3-Component decomposition (mf3cc)#

polsartools.mf3cc(in_dir, chi=45, psi=0, win=1, fmt='tif', cog=False, ovr=[2, 4, 8, 16], comp=False, max_workers=None, block_size=(512, 512), progress_callback=None)[source]

Perform Model-Free 3-Component Decomposition for compact-pol SAR data.

This function implements the model-free three-component decomposition for compact-polarimetric SAR data, decomposing the total backscattered power into surface (Ps), double-bounce (Pd), and volume (Pv) scattering components, along with the scattering-type parameter (Theta_CP).

Examples

>>> # Basic usage with default parameters
>>> mf3cc("/path/to/cp_data")

>>> # Advanced usage with custom parameters
>>> mf3cc(
...     in_dir="/path/to/cp_data",
...     chi=-45,
...     win=5,
...     fmt="tif",
...     cog=True,
...     block_size=(1024, 1024)
... )
Parameters:

  • in_dir (str) – Path to the input folder containing compact-pol C2 matrix files.

  • chi (float, default=45) – Ellipticity angle chi of the transmitted wave in degrees. For circular polarization, chi = 45° (right circular) or -45° (left circular).

  • psi (float, default=0) – Orientation angle psi of the transmitted wave in degrees. For circular polarization, typically 0°.

  • win (int, default=1) – Size of the spatial averaging window. Larger windows reduce speckle noise but decrease spatial resolution.

  • fmt ({'tif', 'bin'}, default='tif') – Output file format: - ‘tif’: GeoTIFF format with georeferencing information - ‘bin’: Raw binary format

  • cog (bool, default=False) – If True, creates Cloud Optimized GeoTIFF (COG) outputs with internal tiling and overviews for efficient web access.

  • ovr (list[int], default=[2, 4, 8, 16]) – Overview levels for COG creation. Each number represents the decimation factor for that overview level.

  • comp (bool, default=False) – If True, applies LZW compression to the output GeoTIFF files.

  • max_workers (int | None, default=None) – Maximum number of parallel processing workers. If None, uses CPU count - 1 workers.

  • block_size (tuple[int, int], default=(512, 512)) – Size of processing blocks (rows, cols) for parallel computation. Larger blocks use more memory but may be more efficient.

Returns:

Writes four output files to disk: 1. Ps_mf3cc: Surface scattering power component 2. Pd_mf3cc: Double-bounce scattering power component 3. Pv_mf3cc: Volume scattering power component 4. Theta_CP_mf3cc: Scattering-type parameter

Return type:

None

The formulation of the scattering powers (\(P_s\) : Surface, \(P_d\): Double bounce, \(P_v\): volume) is as follows:

\[\begin{split}P_{d}^{\text{CP}}=\frac{m_{\text{FP}}{S_0}}{2}{\left(1-\sin2\theta_{\text{CP}}\right)};\\P_{v}^{\text{CP}}={S_0}\left(1-m_{\text{CP}}\right);\\P_{s}^{\text{CP}}=\frac{m_{\text{CP}}{S_0}}{2}\left(1+\sin2\theta_{\text{CP}}\right)\end{split}\]

where \(m_\text{CP}\) is degree of polarization; \(\theta_\text{CP}\) : scattering type parameter; \(S_0, S_3\), are Stokes parameters. The derivation of these parameters in-terms of covariance matrix (C2) elements is as shown below. Further details can be obtained from [[4]](#4)

\[\begin{split}m_{\text{CP}}=\sqrt{1-\frac{4|\mathbf{C2}|}{\big(\mathrm{Trace}(\mathbf{C2})\big)^2}};\qquad{}\tan\theta_{\text{CP}}=\frac{m_{\text{CP}}{S_0}\left(\text{OC}-\text{SC}\right)}{\text{OC}\times\text{SC}+m_{\text{CP}}^{2}{S_0}^{2}}\\ S_0=\text{C11+C22};\qquad{}\qquad{}\qquad{}\qquad{}\qquad{}S_1=\text{C11-C22};\\ S_2=\text{C12+C21};\qquad{}\qquad{}\qquad{}\qquad{}S_3=\pm\text{j(C12-C21)};\\ \text{SC}=\frac{S_0-S_3}{2};\qquad{}\qquad{}\qquad{}\qquad{}\qquad{}\text{OC}=\frac{S_0+S_3}{2};\end{split}\]

This Page