H/A/α Decomposition (h_a_alpha_fp) — PolSARtools 0.11 documentation

Skip to main content
`Ctrl`+`K`

# H/A/α Decomposition (`h_a_alpha_fp`)

polsartools.h_a_alpha_fp(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 H/A//α (Entropy/Anisotropy/Alpha) decomposition for full-pol SAR data.

  This function implements the Cloude-Pottier decomposition, computing entropy (H), alpha angle (α), anisotropy (A), and normalized eigenvalues from full-polarimetric SAR coherency (T3) or covariance (C3) matrices. This decomposition is fundamental for understanding scattering mechanisms in polarimetric SAR data.

  Examples

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

      >>> # Advanced usage with custom parameters
      >>> h_a_alpha_fp(
      ...     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 improve eigenvalue/eigenvector estimation 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 six output files to disk: 1. H_fp: Entropy (H) [0-1] 2. alpha_fp: Alpha angle (α) [0°-90°] 3. anisotropy_fp: Anisotropy (A) [0-1] 4. e1_norm: Normalized first eigenvalue 5. e2_norm: Normalized second eigenvalue 6. e3_norm: Normalized third eigenvalue

  Return type:

    None

  Notes

  The H/α/A decomposition provides three main parameters:

  1. Entropy (H): - Range: [0, 1] - H = 0: Single scattering mechanism - H = 1: Random mixture of scattering mechanisms - Formula: H = -∑(pᵢ log₃(pᵢ)), where pᵢ are normalized eigenvalues

  2. Alpha angle (α): - Range: [0°, 90°] - α ≈ 0°: Surface scattering - α ≈ 45°: Volume scattering - α ≈ 90°: Double-bounce scattering - Formula: α = ∑(pᵢαᵢ), where αᵢ are individual alpha angles

  3. Anisotropy (A): - Range: [0, 1] - Measures relative importance of secondary mechanisms - A = (λ₂ - λ₃)/(λ₂ + λ₃), where λᵢ are eigenvalues

  References

  - Cloude, S.R. and Pottier, E., 2002. An entropy based classification scheme for land applications of polarimetric SAR. IEEE transactions on geoscience and remote sensing, 35(1), pp.68-78.