add support for InSAR Explorer (#1330)

+ add `save_explorer` to support exporting to GRD format, compatible with QGIS InSAR Explorer plugin.

+ `docs/QGIS.md`: update documentation for InSAR Explorer

---------

Co-authored-by: sourcery-ai[bot] <58596630+sourcery-ai[bot]@users.noreply.github.com>
Co-authored-by: Zhang Yunjun <yunjunz@outlook.com>

Author: 3 people

docs/QGIS.md

@@ -1,9 +1,82 @@
-Displacement time-series can be exported as QGIS PS Time Series Viewer plugin compatible *.shp file via `save_qgis.py`.
+The displacement time-series result can be exported as a QGIS-compatible format for visualization via the **InSAR Explorer** plugin or the **PS Time Series Viewer** plugin.
+
+### 1. QGIS with [InSAR Explorer](https://insar-explorer.readthedocs.io/) ###
+
+The InSAR Explorer plugin supports both the GRD format and the shapefile format.
+
+#### a. Setup ####
+
+1. Download and install [QGIS](https://qgis.org/en/site/) if you have not done so.
+2. Install the plugin:
+  - Install within QGIS via "Plugins -> Manage and Install Plugins", then search for "InSAR Explorer".
+  - Alternatively, download the plugin as a *.zip file from [the plugin page](https://plugins.qgis.org/plugins/insar_explorer-dev/), and install it through "Plugins -> Manage and Install Plugins -> Install from ZIP".
+3. Launch the plugin: Access it from the toolbar or through "Plugins -> InSAR Explorer -> InSAR Explorer".
+
+#### b. Usage for GRD files ####
+
+1. Export MintPy results to GRD files using `save_explorer.py`:
+
+```bash
+save_explorer.py geo_timeseries.h5 -v geo_velocity.h5 -o geo_maskTempCoh.h5 -o timeseries/
+```
+
+2. Load data in QGIS: Open one of the exported GRD files, e.g., `geo_velocity_mm.h5`, in QGIS.
+3. Launch InSAR Explorer and click on any point to plot the time series.
+
+<p align="left">
+  <img width="1000" src="https://insarlab.github.io/figs/docs/mintpy/QGIS-InSAR-Explorer-point.png">
+</p>
+
+#### c. Using shapefile ###
+
+1. Export MintPy results to a shapefile using `save_qgis.py`:
+
+```bash
+save_qgis.py timeseries_ERA5_ramp_demErr.h5 -g inputs/geometryRadar.h5
+save_qgis.py geo/geo_timeseries_ERA5_ramp_demErr.h5 -g geo/geo_geometryRadar.h5
+```
+
+2. Load data in QGIS: Browse to the *.shp file generated by `save_qgis.py` and add it to the layer. Then open "View -> Panels -> Layer Styling", and on the right choose "Fill color -> Edit" and add the command below to color-code the map based on velocity value.
+
+```
+ramp_color('RdBu', scale_linear(VEL, -20, 20, 0, 1))
+```
+
+<p align="left">
+  <img width="1000" src="https://insarlab.github.io/figs/docs/mintpy/QGIS-PS-TSV-map.png">
+</p>
+
+3. Launch InSAR Explorer and click on any point to plot the time series.
+
+<p align="left">
+  <img width="1000" src="https://insarlab.github.io/figs/docs/mintpy/QGIS-InSAR-Explorer-point.png">
+</p>
+
+### d. More information ###
+
+For more details on using the plugin, please refer to the [InSAR Explorer documentation](https://insar-explorer.readthedocs.io/).
+
+### 2. QGIS with [PS Time Series Viewer](https://plugins.qgis.org/plugins/pstimeseries/)
+
+The PS Time Series Viewer plugin supports the shapefile format only.
+
+#### a. Setup
 
 1. Download and install [QGIS](https://qgis.org/en/site/) if you have not done so.
-2. Download [ps-time-series](https://plugins.qgis.org/plugins/pstimeseries/) plugin as a *.zip file; and install it to QGIS through "Plugins -> Manage and install Plugins -> install from ZIP".
-3. On the left side of QGIS window, browse to the *.shp file generated by `save_qgis.py` and add to the layer.
-4. Open "View -> Panels -> Layer Styling", then on the right choose "Fill color -> Edit" and add the command below to color code the map based on velocity value.
+2. Install the plugin:
+  - Install within QGIS via "Plugins -> Manage and Install Plugins", then search "PS Time Series Viewer".
+  - Alternatively, download the plugin as a *.zip file from [the plugin page](https://plugins.qgis.org/plugins/pstimeseries/), and install it through “Plugins -> Manage and Install Plugins -> Install from ZIP”.
+
+#### b. Usage
+
+1. Export MintPy results to shapefiles using `save_qgis.py`:
+
+```bash
+save_qgis.py timeseries_ERA5_ramp_demErr.h5 -g inputs/geometryRadar.h5
+save_qgis.py geo/geo_timeseries_ERA5_ramp_demErr.h5 -g geo/geo_geometryRadar.h5
+```
+
+2. Load data in QGIS: Browse to the *.shp file generated by `save_qgis.py` and add it to the layer. Then open "View -> Panels -> Layer Styling", and on the right choose "Fill color -> Edit" and add the command below to color-code the map based on velocity value.
 
 ```
 ramp_color('RdBu', scale_linear(VEL, -20, 20, 0, 1))
@@ -13,7 +86,7 @@ ramp_color('RdBu', scale_linear(VEL, -20, 20, 0, 1))
   <img width="1000" src="https://insarlab.github.io/figs/docs/mintpy/QGIS-PS-TSV-map.png">
 </p>
 
-5. Click the [PS Time Series Viewer logo](https://gitlab.com/faunalia/ps-speed/blob/master/icons/logo.png) to activate the tool, and click/play on the map to display the time-series!
+3. Launch PS Time Series Viewer: Access it from the toolbar or through “Plugins -> Permanent Scatterers -> PS Time Series Viewer”.
 
 <p align="left">
   <img width="800" src="https://insarlab.github.io/figs/docs/mintpy/QGIS-PS-TSV-point.png">

pyproject.toml

@@ -85,6 +85,7 @@ Issues = "https://github.com/insarlab/MintPy/issues"
 "save_kmz_timeseries.py" = "mintpy.cli.save_kmz_timeseries:main"
 "save_qgis.py" = "mintpy.cli.save_qgis:main"
 "save_roipac.py" = "mintpy.cli.save_roipac:main"
+"save_explorer.py" = "mintpy.cli.save_explorer:main"
 "smallbaselineApp.py" = "mintpy.cli.smallbaselineApp:main"
 "solid_earth_tides.py" = "mintpy.cli.solid_earth_tides:main"
 "spatial_average.py" = "mintpy.cli.spatial_average:main"

src/mintpy/__main__.py

@@ -413,6 +413,13 @@ def get_save_roipac_parser(subparsers=None):
     return parser
 
 
+def get_save_explorer_parser(subparsers=None):
+    from mintpy.cli import save_explorer
+    parser = save_explorer.create_parser(subparsers)
+    parser.set_defaults(func=save_explorer.main)
+    return parser
+
+
 def get_smallbaselineApp_parser(subparsers=None):
     from mintpy.cli import smallbaselineApp
     parser = smallbaselineApp.create_parser(subparsers)
@@ -660,6 +667,7 @@ def get_parser():
     get_save_kmz_parser(sp)
     get_save_qgis_parser(sp)
     get_save_roipac_parser(sp)
+    get_save_explorer_parser(sp)
 
     # visualization
     get_info_parser(sp)

src/mintpy/cli/save_explorer.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+############################################################
+# Program is part of MintPy                                #
+# Copyright (c) 2013, Zhang Yunjun, Heresh Fattahi         #
+# Author: Mahmud Haghighi, Mar 2025                        #
+############################################################
+
+
+import sys
+
+from mintpy.utils import readfile
+from mintpy.utils.arg_utils import create_argument_parser
+
+####################################################################################
+EXAMPLE = """example:
+  save_explorer.py geo_timeseries_demErr.h5
+  save_explorer.py geo_timeseries_demErr.h5 -v geo_velocity.h5 -m geo_maskTempCoh.h5
+  save_explorer.py timeseries_demErr.h5 -v velocity.h5 -m maskTempCoh.h5 -o timeseries
+  # check more info on InSAR Explorer documentation: https://luhipi.github.io/insar-explorer
+"""
+
+
+def create_parser(subparsers=None):
+    synopsis = 'Convert time series to GRD files for QGIS InSAR Explorer plugin.'
+    epilog =  EXAMPLE
+    name = __name__.split('.')[-1]
+    parser = create_argument_parser(
+        name, synopsis=synopsis, description=synopsis, epilog=epilog, subparsers=subparsers)
+
+    parser.add_argument('ts_file',
+                        help='Time series file to be converted, in geo coordinate.')
+    parser.add_argument('-v', '--vel', dest='vel_file',
+                        help='velocity file to be converted, in geo coordinate.')
+    parser.add_argument('-m', '--mask', dest='msk_file',
+                        help='mask file, in geo coordinates.')
+    parser.add_argument('-o', '--output', dest='outdir', default='InSAR-Explorer',
+                        help='Output directory for GRD files (default: %(default)s).')
+    return parser
+
+
+def cmd_line_parse(iargs=None):
+    '''Command line parser.'''
+    # parse
+    parser = create_parser()
+    inps = parser.parse_args(args=iargs)
+
+    # check: input time series file is geocoded time series
+    atr = readfile.read_attribute(inps.ts_file)
+    ftype = atr['FILE_TYPE']
+    if 'Y_FIRST' not in atr.keys():
+        raise Exception('Input file is NOT geocoded! Only geocoded files are supported.')
+    if ftype not in ['timeseries']:
+        raise Exception(f'Input file ({ftype}) is NOT time series!')
+
+    return inps
+
+
+####################################################################################
+def main(iargs=None):
+    # parse
+    inps = cmd_line_parse(iargs)
+
+    # import
+    from mintpy.save_explorer import save_explorer
+
+    # run
+    save_explorer(inps)
+
+
+####################################################################################
+if __name__ == '__main__':
+    main(sys.argv[1:])

src/mintpy/save_explorer.py

@@ -0,0 +1,91 @@
+############################################################
+# Program is part of MintPy                                #
+# Copyright (c) 2013, Zhang Yunjun, Heresh Fattahi         #
+# Author: Mahmud Haghighi, Mar 2025                        #
+############################################################
+
+
+import os
+
+import numpy as np
+
+from mintpy.objects import timeseries
+from mintpy.save_gmt import write_grd_file
+from mintpy.utils import ptime, readfile
+
+
+####################################################################################
+def convert2mm(data, atr):
+    """Convert displacement (velocity) data to mm or mm/year."""
+    if atr['UNIT'] in ['m', 'm/year']:
+        return data * 1000
+    elif atr['UNIT'] in ['cm', 'cm/year']:
+        return data * 10
+    elif atr['UNIT'] in ['mm', 'mm/year']:
+        return data
+    else:
+        raise ValueError(f"ERROR: unit {atr['UNIT']} is not supported!")
+
+
+def save_explorer(inps):
+
+    # create output directory
+    inps.outdir = os.path.abspath(inps.outdir)
+    print(f'output directory: {inps.outdir}')
+    if not os.path.isdir(inps.outdir):
+        print('output directory does not exist, creating directory: '+inps.outdir)
+        os.makedirs(inps.outdir)
+
+    # grab aux files'name based on input ts_file file name
+    inps.ts_file = os.path.abspath(inps.ts_file)
+    ts_dir = os.path.dirname(inps.ts_file)
+    prefix = 'geo_' if os.path.basename(inps.ts_file).startswith('geo_') else ''
+    inps.vel_file = inps.vel_file or os.path.join(ts_dir, f'{prefix}velocity.h5')
+    inps.msk_file = inps.msk_file or os.path.join(ts_dir, f'{prefix}maskTempCoh.h5')
+
+    # check aux file existence
+    inps.vel_file = os.path.abspath(inps.vel_file) if os.path.isfile(inps.vel_file) else None
+    inps.msk_file = os.path.abspath(inps.msk_file) if os.path.isfile(inps.msk_file) else None
+    print(f'time series file: {inps.ts_file}')
+    print(f'velocity    file: {inps.vel_file}')
+    print(f'mask        file: {inps.msk_file}')
+
+    # read mask file
+    if inps.msk_file and os.path.isfile(inps.msk_file):
+        print(f'read mask data from file: {inps.msk_file}')
+        mask = readfile.read(inps.msk_file)[0]
+    else:
+        mask = None
+
+    # export velocity file
+    if inps.vel_file and os.path.isfile(inps.vel_file):
+        data, atr = readfile.read(inps.vel_file)
+        data = convert2mm(data, atr)  # convert to mm
+        if mask is not None:
+            data[~mask] = np.nan
+
+        out_base = os.path.splitext(os.path.basename(inps.vel_file))[0]
+        out_file = os.path.join(inps.outdir, f'{out_base}_mm.grd')
+        write_grd_file(data, atr, out_file, print_msg=True)
+
+    # export time series to a list of grd files
+    print('writing time series to a list of timeseries-{YYYYMMDD}_mm.grd files ...')
+    date_list = timeseries(inps.ts_file).get_date_list()
+    num_date = len(date_list)
+    prog_bar = ptime.progressBar(maxValue=num_date)
+    for i, date_str in enumerate(date_list):
+        prog_bar.update(i+1, suffix=f'{i+1}/{num_date} {date_str}')
+
+        # read
+        data, atr = readfile.read(inps.ts_file, datasetName=date_str)
+        data = convert2mm(data, atr)  # convert to mm
+        if mask is not None:
+            data[mask==0] = np.nan
+
+        # write
+        out_file = os.path.join(inps.outdir, f'timeseries-{date_str}_mm.grd')
+        write_grd_file(data, atr, out_file, print_msg=False)
+    prog_bar.close()
+
+    print('Done.')
+    return

src/mintpy/save_gmt.py

@@ -101,7 +101,7 @@ def get_geo_lat_lon(atr):
     return Y, X
 
 
-def write_grd_file(data, atr, out_file=None):
+def write_grd_file(data, atr, out_file=None, print_msg=True):
     """Write GMT .grd file for input data matrix, using giant._gmt module.
     Parameters: data     - 2D np.ndarray in int/float, data matrix to write
                 atr      - dict, attributes of input data matrix
@@ -112,7 +112,8 @@ def write_grd_file(data, atr, out_file=None):
     lats, lons = get_geo_lat_lon(atr)
 
     # writing
-    print('writing >>> '+out_file)
+    if print_msg:
+        print('writing >>> '+out_file)
     write_gmt_simple(
         lons=lons,
         lats=np.flipud(lats),