Multi-looking (mlook)

polsartools.mlook(infolder, azlks=2, rglks=2, outType='tif', sub_dir=True, cog_flag=False, cog_overviews=[2, 4, 8, 16], write_flag=True, max_workers=None, block_size=(512, 512), progress_callback=None)

Generate multilooked polarimetric matrix from C4, T4, C3, T3, C2, or T2 formats.

This function applies multilooking (spatial averaging) to reduce speckle noise and improve radiometric stability in polarimetric SAR datasets.

Examples

>>> # Basic usage with default look factors
>>> mlook("/path/to/polSAR_data")

>>> # With 3 azimuth and 2 range looks, and COG GeoTIFF output
>>> mlook("/path/to/polSAR_data", azlks=3, rglks=2, outType="tif", cog_flag=True)

Parameters:

• infolder (str) – Path to the input folder containing a supported polarimetric matrix.

• azlks (int, default=2) – Number of looks in azimuth (vertical) direction.

• rglks (int, default=2) – Number of looks in range (horizontal) direction.

• outType ({'tif', 'bin'}, default='tif') – Output format: - ‘tif’: Cloud-optimized GeoTIFF (if cog_flag is True) - ‘bin’: Raw binary format

• cog_flag (bool, default=False) – Enable Cloud Optimized GeoTIFF output with internal overviews and tiling.

• cog_overviews (list[int], default=[2, 4, 8, 16]) – Overview levels for pyramid generation (used with COGs).

• write_flag (bool, default=True) – Whether to write the multilooked data to disk or return only in-memory.

• max_workers (int | None, default=None) – Maximum number of parallel worker threads (defaults to all available CPUs).

• block_size (tuple[int, int], default=(512, 512)) – Size of processing blocks for chunked and parallel execution.

Returns:

The multilooked output matrix is saved to disk. Number and names of output files depend on matrix type (e.g., C3 → C11.tif, C12_real.tif, etc.).

Return type:

None

Notes

• Supported polarimetric matrices: ‘C4’, ‘T4’, ‘C3’, ‘T3’, ‘C2’, ‘T2’

• Automatically detects matrix type and file extension (.bin or .tif)

• Handles real and complex-valued data appropriately (e.g., multilooks real and imag separately)

• Output pixel spacing is updated in geotransform metadata based on look factors

Conver full-pol S2 (convert_S)

polsartools.convert_S(infolder, matrixType='T3', azlks=4, rglks=2, cf=1, outType='tif', outfolder=None, cog_flag=False, cog_overviews=[2, 4, 8, 16], write_flag=True, max_workers=None, block_size=(512, 512), progress_callback=None)

Convert full/dual-polarimetric scattering (S2,Sxy) matrix into multi-looked coherency (T4, T3, T2) or covariance (C4, C3, C2) matrices. It supports both GeoTIFF and PolSARpro-compatible output.

Examples

>>> # Convert to C3 matrix with 10x5 multi-looking
>>> convert_S("/path/to/S_data", matrix="C3", azlks=10, rglks=5)

>>> # Output as tiled GeoTIFF with Cloud Optimized overviews
>>> convert_S("/data/S_data", matrix="C2", cog_flag=True)

Parameters:

• infolder (str) – Path to the input folder containing S11, S12, S21, S22 scattering components.

• matrixType (str, default='T3') – Output matrix format. Supported values: - ‘T4’, ‘T3’, ‘T2HV’ (Coherency) - ‘C4’, ‘C3’, ‘C2HX’, ‘C2VX’, ‘C2HV’ (Covariance)

• azlks (int, default=4) – Number of looks in azimuth direction.

• rglks (int, default=2) – Number of looks in range direction.

• cf (float, default=1) – Calibration factor (linear) to adjust the amplitude of S2 data.

• outType ({'tif', 'bin'}, default='tif') – Output format type.

• cog_flag (bool, default=False) – If True, creates Cloud Optimized GeoTIFF (COG).

• cog_overviews (list[int], default=[2, 4, 8, 16]) – Levels of pyramid overviews for COG generation.

• write_flag (bool, default=True) – If False, skips writing output to disk.

• max_workers (int | None, default=None) – Number of parallel worker threads.

• block_size (tuple[int, int], default=(512, 512)) – Size of chunks for processing.

Returns:

Writes multi-looked polarimetric matrix to disk in the selected format.

Return type:

None

Derive stokes parameters (stokes_parm)

polsartools.stokes_parm(SxxFile, SxyFile, window_size=3, outType='tif', cog_flag=False, cog_overviews=[2, 4, 8, 16], write_flag=True, max_workers=None, block_size=(512, 512), progress_callback=None)

This function computes the Stokes parameters and child parameters from Single look Scattering Matrix elements.

Examples

>>> # Basic usage with default parameters
>>> stokes_parm("/path/to/s11.bin", "/path/to/s21.bin")

>>> # Advanced usage with custom parameters
>>> stokes_parm(
...     "/path/to/s11.bin",
...     "/path/to/s21.bin",
...     window_size=5,
...     outType="tif",
...     cog_flag=True,
...     block_size=(1024, 1024)
... )

Parameters:

• SxxFile (str) – Path to the Sxx file.

• SxyFile (str) – Path to the Sxy file.

• window_size (int, default=3) – Size of the spatial averaging window.

• 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:

• None

• Writes stkokes and child parameters to disk –

  • stokes_g0 (.bin or .tif)

  • stokes_g1 (.bin or .tif)

  • stokes_g2 (.bin or .tif)

  • stokes_g3 (.bin or .tif)

  • stokes_e1 (.bin or .tif)

  • stokes_e2 (.bin or .tif)

  • stokes_e1norm (.bin or .tif)

  • stokes_e2norm (.bin or .tif)

  • stokes_phi (.bin or .tif)

  • stokes_tau (.bin or .tif)

  • stokes_x_poincare (.bin or .tif)

  • stokes_y_poincare (.bin or .tif)

  • stokes_H (.bin or .tif)

  • stokes_A (.bin or .tif)

  • stokes_contrast (.bin or .tif)

  • stokes_DoL (.bin or .tif)

  • stokes_DoCP (.bin or .tif)

  • stokes_LPR (.bin or .tif)

  • stokes_CPR (.bin or .tif)

Prepare DEM (prepare_dem)

polsartools.prepare_dem(bbox, out_path='dem.tif', dem_type='SRTM1', hgt_dir='hgt_tiles', apply_correction=True, clip=True, clean_tiles=True)

Prepares a Digital Elevation Model (DEM) from downloaded elevation tiles.

This function downloads elevation tiles based on a bounding box, mosaics them into a single raster, optionally applies ellipsoid height correction, clips to the bounding box, and saves the result as a GeoTIFF. Temporary tile files can be cleaned up after processing.

Examples

>>> bbox = (-70.2, 43.5, -66.2, 45.8)  # xmin, ymin, xmax, ymax
>>> prepare_dem(bbox, out_path="SRTM1_mosaic_clip.tif")
>>> prepare_dem(bbox, out_path="SRTM3_mosaic_clip.tif", dem_type="SRTM3")

Parameters:

• bbox (tuple of float) – Bounding box in the format (xmin, ymin, xmax, ymax), in geographic coordinates (longitude, latitude).

• out_path (str, optional) – Path to save the output DEM GeoTIFF file. Defaults to “dem.tif”.

• dem_type (str, optional) – Type of DEM source. Options include “SRTM1”, “SRTM3”, “COP30”, “COP90”. Defaults to “SRTM1”.

• hgt_dir (str, optional) – Directory to store downloaded tiles. Defaults to “hgt_tiles”.

• apply_correction (bool, optional) – Whether to apply WGS84ellipsoid height correction to SRTM tiles. Defaults to True.

• clip (bool, optional) – Whether to clip the output DEM to the bounding box. Defaults to False.

• clean_tiles (bool, optional) – Whether to delete the tile directory after processing. Defaults to True.

Returns:

The function saves the DEM to the specified out_path.

Return type:

None

Notes

• Uses GDAL for mosaicking and warping.

• Supports ellipsoid correction for SRTM1 and SRTM3.

• Automatically creates empty tiles for missing SRTM1 data.