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)[source]

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)[source]

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)[source]

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)

Generate pauliRGB for FP data (pauliRGB)#

polsartools.pauliRGB(infolder, save_tif=False, window_size=None)[source]

Generate Pauli RGB image from polarimetric SAR data (C4, C3, T4, T3, or S2 matrices).

This function creates a Pauli decomposition RGB composite image from full polarimetric SAR data.

Examples

>>> # Generate Pauli RGB from a polarimetric folder
>>> pauliRGB("/path/to/polSAR_data")

>>> # Output both PNG and GeoTIFF versions
>>> pauliRGB("/path/to/polSAR_data", tif_flag=True)
Parameters:

  • infolder (str) – Path to the folder containing polarimetric matrix files (.bin or .tif). Supports full- and dual-pol data in formats: C4, C3, T4, T3, or S2.

  • save_tif (bool, default=False) – If True, generates both PNG and GeoTIFF (.tif) versions of the Pauli RGB image.

  • window_size (int, optional) – Size of the moving average window for smoothing. If None, no smoothing is applied.

Returns:

  • None

  • Writes output to –

    • PauliRGB.png: RGB composite with world file for georeferencing

    • PauliRGB.tif: Optional GeoTIFF output if tif_flag=True

Generate false color RGB for DP/CP data (dxpRGB)#

polsartools.dxpRGB(infolder, type=1, save_tif=False, window_size=None)[source]

Generate false-color RGB visualization from dual-polarimetric Sxy, C2 SAR data.

This function creates an RGB image from dual-pol (Sxy, C2) matrix inputs.

Examples

>>> # Generate type-1 false-color RGB from C2 folder
>>> dxpRGB("/path/to/data")

>>> # Output both PNG and GeoTIFF versions
>>> dxpRGB("/path/to/data", type=3, tif_flag=True)
Parameters:

  • infolder (str) – Path to the input folder containing C2 matrix components (C11, C22, C12_real).

  • type (int, {1, 2, 3, 4}, default=1) – RGB combination type: - 1: Blue=C11, Red=C22, Green=|C11 + C22 - 2·C12_real| - 2: Blue=C22, Red=C11, Green=|C11 + C22 - 2·C12_real| - 3: Blue=C11, Red=C22, Green=|C11 - C22| - 4: Blue=C22, Red=C11, Green=|C22 - C11|

  • save_tif (bool, default=False) – If True, generates a GeoTIFF (.tif) file alongside the PNG image.

Returns:

Writes RGB visualization to disk: - ‘RGB#.png’: False-color PNG image (with world file for georeferencing) - ‘RGB#.tif’: Optional GeoTIFF output if tif_flag=True

Return type:

None

Generate false color RGB for decomposed powers (rgb)#

polsartools.rgb(Rpath, Gpath, Bpath, norm_each=False, lp=5, gp=95, save_tif=False, window_size=None)[source]

Generate false-color RGB visualization from three input raster files.

Examples

>>> # Generate Pauli RGB from a polarimetric folder
>>> rgb("/path/to/red.tif", "/path/to/green.tif", "/path/to/blue.tif")

>>> # Output both PNG and GeoTIFF versions
>>> rgb("/path/to/red.tif", "/path/to/green.tif", "/path/to/blue.tif", tif_flag=True)
Parameters:

  • Rpath (str) – Path to the red channel raster file.

  • Gpath (str) – Path to the green channel raster file.

  • Bpath (str) – Path to the blue channel raster file.

  • norm_each (bool, default=False) – If True, normalize each channel separately.

  • lp (int, default=5) – Lower percentile for normalization (0-100). Only used if norm_each=True.

  • gp (int, default=95) – Upper percentile for normalization(0-100). Only used if norm_each=True.

  • save_tif (bool, default=False) – If True, generates a GeoTIFF (.tif) file alongside the PNG image.

  • window_size (int, optional) – Size of the moving average window for smoothing. If None, no smoothing is applied.

Returns:

  • None

  • Writes output to

  • - RGB.png (RGB composite with world file for georeferencing)

  • - RGB.tif (Optional GeoTIFF output if tif_flag=True)

Generate polarimetric signatures for FP data (fp_sign)#

polsartools.fp_sign(S2=None, title='', pname='', cmap='jet', plotType=1, fig=None, axes=None, start_index=0)[source]

Generates and visualizes polarimetric signatures from a given 2x2 scattering matrix (S2).

Examples

>>> S2 = np.array([[1, 0], [0, 1]]) # Trihedral
>>> fp_sign(S2, title='Trihedral', plotType=1)
Parameters:

  • S2 (np.2darray (2x2) or None) – Complex 2x2 scattering matrix representing polarimetric data. Is None, for theoretical plot that don’t require S2 will be generated.

  • title (str, optional) – Title of the plot. Default is an empty string.

  • pname (str, optional) – Name of the output file (*.png). Default is an empty string.

  • cmap (str, optional) – Colormap used for visualizing the data. Default is ‘jet’.

  • plotType (int, optional) –

    Determines the type of plot to generate:

    • 1: Standard polarimetric signature via pol_sign.

    • 2: 2D polarimetric signature via pol_sign2d.

    • 3: Poincaré sphere mapping via poincare_plot.

    • 4: Render empty or canonical Poincaré sphere via poincare_sphere (S2 not required).