Shannon entropy (shannon_h_fp) — PolSARtools 0.8 documentation

Skip to main content
`Ctrl`+`K`

# Shannon entropy (`shannon_h_fp`)

polsartools.shannon_h_fp(infolder, window_size=1, outType='tif', cog_flag=False, cog_overviews=[2, 4, 8, 16], write_flag=True, max_workers=None, block_size=(512, 512), progress_callback=None)

  Calculate Shannon Entropy parameters from full-pol SAR data.

  This function computes three Shannon Entropy-based parameters from full-polarimetric SAR data: total Shannon Entropy (H), intensity contribution (HI), and polarimetric contribution (HP). These parameters provide information about the complexity and disorder of the scattered wave field.

  Examples

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

      >>> # Advanced usage with custom parameters
      >>> shannon_h_fp(
      ...     infolder="/path/to/fullpol_data",
      ...     window_size=5,
      ...     outType="tif",
      ...     cog_flag=True,
      ...     block_size=(1024, 1024)
      ... )

  Parameters:

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

    - window_size (int, default=1) – Size of the spatial averaging window. Larger windows provide better entropy estimation but decrease spatial resolution.

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

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

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

    - write_flag (bool, default=True) – If True, writes results to disk. If False, only processes data in memory.

    - 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 three output files to disk: 1. H_Shannon: Total Shannon Entropy 2. HI_Shannon: Intensity contribution 3. HP_Shannon: Polarimetric contribution

  Return type:

    None

  Notes

  Shannon Entropy Components:

  1. Total Shannon Entropy (H): - H = HI + HP - Represents total information content - Higher values indicate more complex scattering - Useful for overall scene complexity assessment

  2. Intensity Contribution (HI): - HI = log(π·e·IC) - IC: intensity component - Related to total backscattered power - Sensitive to surface roughness and moisture - Independent of polarimetric information

  3. Polarimetric Contribution (HP): - HP = log(1-|ρ|²) - |ρ|: degree of polarization - Measures polarimetric complexity - Independent of total power - Sensitive to scattering mechanism diversity