Generalized volume based Radar Vegetation Index (grvi) — PolSARtools 0.8 documentation

Skip to main content
`Ctrl`+`K`

# Generalized volume based Radar Vegetation Index (`grvi`)

polsartools.grvi(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 Generalized volume based Radar Vegetation Index (GRVI) from full-pol SAR data.

  This function computes the Generalized volume based Radar Vegetation Index (GRVI) using full-polarimetric SAR data from either coherency (T3) or covariance (C3) matrices. GRVI is an advanced vegetation index that accounts for various scattering mechanisms and is particularly effective for vegetation structure characterization.

  Examples

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

      >>> # Advanced usage with custom parameters
      >>> grvi(
      ...     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 reduce speckle noise 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 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:

    Writes one output file to disk: - ‘grvi.tif’ or ‘grvi.bin’: GRVI image

  Return type:

    None

The formulation of GRVI is as follows:

\[\text{GRVI} = \left(1 - \text{GD}_{\text{GV}}\right)\Big(\frac{p}{q}\Big)^{2\,\text{GD}_{\text{GV}}}, \quad 0\le \text{GRVI} \le 1\]

where, \(\text{GD}_{\text{GV}}\) is the geodesic distance between Kennaugh \((\mathbf{K})\) matrices of the observed and the generalized volume scattering model, \(p,q\) are minimum and maximum value of distances between \(\mathbf{K}\) matrices of the observed and elementary targets respectively. A detailed explanation of GRVI is available in.