Model Free 3-Component decomposition (mf3cf) — PolSARtools 0.10 documentation

Skip to main content
`Ctrl`+`K`

# Model Free 3-Component decomposition (`mf3cf`)

polsartools.mf3cf(in_dir, win=1, fmt='tif', cog=False, ovr=[2, 4, 8, 16], comp=False, max_workers=None, block_size=(512, 512), progress_callback=None)

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

  This function implements the model-free three-component decomposition for full-polarimetric SAR data, decomposing the total scattered power into surface (Ps), double-bounce (Pd), and volume (Pv) scattering components, along with the scattering type parameter (Theta_FP). Unlike model-based decompositions, this approach doesn’t assume specific scattering models.

  Examples

      >>> # Basic usage with default parameters
      >>> mf3cf("/path/to/fullpol_data")

      >>> # Advanced usage with custom parameters
      >>> mf3cf(
      ...     in_dir="/path/to/fullpol_data",
      ...     win=5,
      ...     fmt="tif",
      ...     cog=True,
      ...     block_size=(1024, 1024)
      ... )

  Parameters:

    - in_dir (str) – Path to the input folder containing full-pol T3 or C3 matrix files.

    - 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, uses LZW compression for GeoTIFF outputs.

    - 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_mf3cf: Surface scattering power component

    2. Pd_mf3cf: Double-bounce scattering power component

    3. Pv_mf3cf: Volume scattering power component

    4. Theta_FP_mf3cf: 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{FP}}=\frac{m_{\text{FP}}{\text{Span}}}{2}{\left(1-\sin2\theta_{\text{FP}}\right)}\\P_{v}^{\text{FP}}={\text{Span}}\left(1-m_{\text{FP}}\right)\\P_{s}^{\text{FP}}=\frac{m_{\text{FP}}{\text{Span}}}{2}\left(1+\sin2\theta_{\text{FP}}\right)\end{split}\]

where \(m_\text{FP}\) is degree of polarization, \(\theta_\text{FP}\) scattering type parameter, Span is the sum of the diagonal elements os coherence matrix (T3). The derivation of these parameters in-terms of coherancey matrix (T3) elements is as shown below. Further details can be obtained from [[4]](#4)

\[ \begin{align}\begin{aligned}m_{\text{FP}}=\sqrt{1-\frac{27|\mathbf{T3}|}{\big(\mathrm{Trace}(\mathbf{T3})\big)^3}};\qquad{}\tan\theta_{\text{FP}}=\frac{m_{\text{FP}}{\text{Span}}\left(T_{11}-T_{22}-T_{33}\right)}{T_{11}\left(T_{22}+T_{33}\right)+m_{\text{FP}}^{2}{\text{Span}}^{2}}\\\text{Span}=T_{11}+T_{22}+T_{33}\end{aligned}\end{align} \]