Compact-pol Radar Vegetation Index (cprvi) — PolSARtools 0.10 documentation

Skip to main content
`Ctrl`+`K`

# Compact-pol Radar Vegetation Index (`cprvi`)

polsartools.cprvi(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 compact-pol Radar Vegetation Index (CpRVI) from C2 matrix data.

  This function processes compact-polarimetric SAR data to generate the CP-RVI, which is useful for vegetation monitoring and biomass estimation using compact-pol SAR systems. The processing is done in parallel blocks for improved performance.

  Examples

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

      >>> # Custom parameters for left circular transmission
      >>> cprvi(
      ...     in_dir="/path/to/cp_data",
      ...     chi=-45,
      ...     psi=0,
      ...     win=3,
      ...     fmt="tif",
      ...     cog=True
      ... )

  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 reduce speckle noise 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 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.

    - 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 ‘cprvi.tif’ or ‘cprvi.bin’ in the input folder.

  Return type:

    None

The formulation of the CpRVI is as follows:

\[\begin{split}\text{CpRVI}=\left(1-\dfrac{3}{2}\text{GD}_{\text{ID}}\right)\Big(\frac{p}{q}\Big)^{2(\frac{3}{2}\text{GD}_{\text{ID}})}\\ p=\text{min\{SC,OC\}},q=\text{max\{SC,OC\}}\\ \text{SC}=\frac{S_0-S_3}{2};\qquad{}\text{OC}=\frac{S_0+S_3}{2};\\ 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}\]

where, \(\text{GD}_\text{ID}\) is the geodesic distance between Kennaugh matrices (\(\mathbf{K}\)) of the observed and the ideal depolarizer, \(p, q\) are minimum and maximum values of \(\text{SC}\) and \(\text{OC}\) which are functions of stocks parameters (\(S_0\), \(S_1\), \(S_2\), and \(S_3\)). A detailed explanation of CpRVI is available in [[6]](#6).