Degree of Polarization (dop_cp) — PolSARtools 0.10 documentation

Skip to main content
`Ctrl`+`K`

# Degree of Polarization (`dop_cp`)

polsartools.dop_cp(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)

  Compute Degree of Polarization (DoP) from compact-pol SAR data.

  This function calculates the Degree of Polarization (DoP) from compact-polarimetric SAR data, which quantifies the polarized portion of the scattered wave. DoP is a useful parameter for characterizing surface properties and scattering mechanisms.

  Examples

      >>> # Basic usage with default parameters (right circular transmission)
      >>> dopcp("/path/to/cp_data")

      >>> # Advanced usage with custom parameters
      >>> dopcp(
      ...     in_dir="/path/to/cp_data",
      ...     chi=-45,  # left circular transmission
      ...     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 provide better estimation of DoP but reduce 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 a Cloud Optimized GeoTIFF (COG) 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:

    Results are written to disk as either ‘dopcp.tif’ or ‘dopcp.bin’ in the input folder. The output DoP values range from 0 to 1, where: - 0 indicates completely unpolarized scattered wave - 1 indicates completely polarized scattered wave

  Return type:

    None

  Notes

  The Degree of Polarization (DoP) is calculated using the Stokes parameters derived from the compact-pol coherency matrix. For a partially polarized wave, DoP is given by:

  DoP = sqrt(S₁² + S₂² + S₃²) / S₀

  where S₀, S₁, S₂, S₃ are the Stokes parameters.

The conventional degree of polarization in terms of stokes paramters can be written as follows:

\[\text{DOP}_{cp}=\frac{\sqrt{S^2_1+S^2_2+S^2_3}}{S_0}\]

where,

\[\begin{split}S_0=\text{C11+C22};\qquad{}S_1=\text{C11-C22};\\ S_2=\text{C12+C21};\qquad{}S_3=\pm\text{j(C12-C21)}\end{split}\]