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)[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(
...     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}\]

This Page