Degree of Polarization (dopcp)#

polsartools.dopcp(infolder, chi_in=45, psi_in=0, 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)[source]

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(
...     infolder="/path/to/cp_data",
...     chi_in=-45,  # left circular transmission
...     window_size=5,
...     outType="tif",
...     cog_flag=True,
...     block_size=(1024, 1024)
... )
Parameters:

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

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

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

  • window_size (int, default=1) – Size of the spatial averaging window. Larger windows provide better estimation of DoP but reduce 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 a Cloud Optimized GeoTIFF (COG) 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:

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.

Key characteristics: - DoP is invariant to the wave polarization basis - Values are normalized between 0 and 1 - Higher values indicate stronger polarized scattering - Lower values suggest depolarizing mechanisms

Common applications: - Surface roughness estimation - Vegetation density analysis - Urban area characterization - Sea ice classification

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}\]

This Page