prep_gmtsar: grab A/RLOOKS from GMTSAR config file if available (#1389)

+ utils.readfile.read_gmtsar_prm(): support reading GMTSAR config file, which may have empty key values or may not have some keys as in the PRM file

+ prep_gmtsar.extract_gmtsar_metadata(): support grabing A/RLOOKS from the config file if available, which is usually named as config.{SAT}.txt, where SAT can be ERS, ENVI, ALOS, ALOS_SLC, ALOS2, ALOS2_SCAN, S1_STRIP, S1_TOPS, CSK_RAW, CSK_SLC, CSG, TSX, RS2, GF3, LT1

+ docs/dir_structure.md: add config.tops.txt file to the example directory

+ docs/demo_dataset.md: update the zenodo link for the new example dataset (with the config.tops.txt file added)

Author: yunjunz

docs/demo_dataset.md

@@ -58,11 +58,11 @@ smallbaselineApp.py ${MINTPY_HOME}/docs/templates/RidgecrestSenDT71.txt
 ### Sentinel-1 on San Francisco Bay with GMTSAR ###
 
 + Area: San Francisco Bay, California, USA
-+ Data: Sentinel-1 A/B descending track 42 during December 2014 - June 2024 (333 acquisitoins; [Zenodo](https://zenodo.org/records/12773014))
++ Data: Sentinel-1 A/B descending track 42 during December 2014 - June 2024 (333 acquisitions; [Zenodo](https://zenodo.org/records/15814132))
 + Size: ~2.3 GB
 
 ```bash
-wget https://zenodo.org/records/12773014/files/SanFranBaySenD42.tar.xz
+wget https://zenodo.org/records/15814132/files/SanFranBaySenD42.tar.xz
 tar -xvJf SanFranBaySenD42.tar.xz
 cd SanFranBaySenD42
 smallbaselineApp.py ${MINTPY_HOME}/docs/templates/SanFranBaySenD42.txt

docs/dir_structure.md

@@ -487,6 +487,7 @@ Below is a recipe to prepare a stack of interferograms from Sentinel-1:
 ```
 $DATA_DIR/SanFranBaySenD42
 ├── baseline_table.dat
+├── config.tops.txt             # configuration file for p2p_processing.csh
 ├── supermaster.PRM
 ├── geometry
 |   ├── dem.grd

src/mintpy/asc_desc2horz_vert.py

@@ -201,10 +201,10 @@ def run_asc_desc2horz_vert(inps):
             print(f'read 2D LOS incidence / azimuth angles from file: {inps.geom_file[i]}')
         else:
             los_inc_angle[i] = ut.incidence_angle(atr, dimension=0, print_msg=False)
-            los_az_angle[i] = ut.heading2azimuth_angle(float(atr['HEADING']))
+            los_az_angle[i] = ut.heading2azimuth_angle(float(atr['HEADING']), look_direction='right')
             print('calculate the constant LOS incidence / azimuth angles from metadata as:')
             print(f'LOS incidence angle: {los_inc_angle[i]:.1f} deg')
-            print(f'LOS azimuth   angle: {los_az_angle[i]:.1f} deg')
+            print(f'LOS azimuth   angle: {los_az_angle[i]:.1f} deg, assuming right-looking radar.')
 
 
     ## 3. decompose LOS displacements into horizontal / Vertical displacements

src/mintpy/prep_gmtsar.py

@@ -90,6 +90,7 @@ def get_lalo_ref(ifg_dir, prm_dict, fbases=['corr', 'phase', 'phasefilt', 'unwra
         return prm_dict
 
     # read corners lat/lon info
+    print(f'grab LAT/LON_REF1/2/3/4 from file: {geo_file}')
     ds = gdal.Open(geo_file, gdal.GA_ReadOnly)
     transform = ds.GetGeoTransform()
     x_step = abs(transform[1])
@@ -138,6 +139,7 @@ def get_slant_range_distance(ifg_dir, prm_dict, fbases=['corr', 'phase', 'phasef
         raise ValueError(f'No radar-coord files found in {ifg_dir} with suffix: {fbases}')
 
     # read width from rdr_file
+    print(f'grab SLANT_RANGE_DISTANCE, INCIDENCE_ANGLE from file: {geo_file}')
     ds = gdal.Open(geo_file, gdal.GA_ReadOnly)
     width = ds.RasterXSize
 
@@ -189,20 +191,53 @@ def extract_gmtsar_metadata(meta_file, unw_file, template_file, rsc_file=None, u
     ifg_dir = os.path.dirname(unw_file)
 
     # 1. read *.PRM file
-    #prm_file = get_prm_files(ifg_dir)[0]
+    # prm_file = get_prm_files(ifg_dir)[0]
+    meta_file = os.path.abspath(meta_file)
+    print(f'extract metadata from metadata file: {meta_file}')
     meta = readfile.read_gmtsar_prm(meta_file)
     meta['PROCESSOR'] = 'gmtsar'
 
-    # 2. read template file: HEADING, ORBIT_DIRECTION
+    # 2. grab A/RLOOKS from config or template file
+    # config file name convention: config.{SAT}.txt, where SAT can be ERS, ENVI, ALOS, ALOS_SLC,
+    # ALOS2, ALOS2_SCAN, S1_STRIP, S1_TOPS, CSK_RAW, CSK_SLC, CSG, TSX, RS2, GF3, LT1
     template = readfile.read_template(template_file)
-    for key in ['HEADING', 'ALOOKS', 'RLOOKS']:
+    config_file = os.path.join(os.path.dirname(meta_file), 'config.*.txt')
+    config_files = glob.glob(config_file)
+
+    if len(config_files) >= 1:
+        # read config file
+        config = readfile.read_gmtsar_prm(config_files[0])
+        filter_wvl = float(config.get('filter_wavelength', 200))
+        # calc a/rlooks
+        # Note from Xiaohua Xu: GMTSAR is applying Gaussian filtering, instead of multilooing,
+        # thus, the equivalent value is ~0.3 times the mainlobe response of the boxcar filtering.
+        print(f'grab A/RLOOKS from config file: {config_file}')
+        meta['ALOOKS'] = np.rint(0.3 * filter_wvl / meta['AZIMUTH_PIXEL_SIZE']).astype(int)
+        meta['RLOOKS'] = np.rint(0.3 * filter_wvl / meta['RANGE_PIXEL_SIZE']).astype(int)
+
+    else:
+        print(f'WARNING: No config file found for {config_file}!')
+        # read from template file
+        for key in ['ALOOKS', 'RLOOKS']:
+            if key in template.keys():
+                print(f'grab {key} from template file: {template_file}')
+                meta[key] = int(template[key])
+            else:
+                msg = f'Attribute {key} is missing! '
+                msg += f'Please manually specify it in the template file: {template_file}'
+                raise ValueError(msg)
+
+    # 2. grab HEADING from template file
+    for key in ['HEADING']:
         if key in template.keys():
+            print(f'grab {key} from template file: {template_file}')
             meta[key] = template[key].lower()
         else:
-            raise ValueError(f'Attribute {key} is missing! Please manually specify it in the template file.')
+            msg = f'Attribute {key} is missing! '
+            msg += f'Please manually specify it in the template file: {template_file}'
+            raise ValueError(msg)
 
-    # 3. grab A/RLOOKS from radar-coord data file
-    #meta['ALOOKS'], meta['RLOOKS'] = get_multilook_number(ifg_dir)
+    # 3. update AZIMUTH/RANGE_PIXEL_SIZE
     meta['AZIMUTH_PIXEL_SIZE'] *= int(meta['ALOOKS'])
     meta['RANGE_PIXEL_SIZE'] *= int(meta['RLOOKS'])
 
@@ -215,6 +250,7 @@ def extract_gmtsar_metadata(meta_file, unw_file, template_file, rsc_file=None, u
     x_step = abs(transform[1])
     y_step = abs(transform[5]) * -1.
     if 1e-7 < x_step < 1.:
+        print(f'grab Y/X_FIRST/STEP from {unw_file}')
         meta['X_STEP'] = x_step
         meta['Y_STEP'] = y_step
         meta['X_FIRST'] = transform[0] - x_step / 2.

src/mintpy/utils/readfile.py

@@ -1788,9 +1788,11 @@ def read_gmtsar_prm(fname, delimiter='='):
     prmDict = {}
     for line in lines:
         c = [i.strip() for i in line.strip().replace('\t',' ').split(delimiter, 1)]
-        key = c[0]
-        value = c[1].replace('\n', '').strip()
-        prmDict[key] = value
+        # ignore lines with empty key values
+        if len(c) >= 2:
+            key = c[0]
+            value = c[1].replace('\n', '').strip()
+            prmDict[key] = value
 
     prmDict = _attribute_gmtsar2roipac(prmDict)
     prmDict = standardize_metadata(prmDict)
@@ -1838,12 +1840,18 @@ def _attribute_gmtsar2roipac(prm_dict_in):
         prm_dict['RANGE_PIXEL_SIZE'] = SPEED_OF_LIGHT / value / 2.0
 
     # SC_clock_start/stop -> CENTER_LINE_TUC
-    dt_center = (float(prm_dict['SC_clock_start']) + float(prm_dict['SC_clock_stop'])) / 2.0
-    t_center = dt_center - int(dt_center)
-    prm_dict['CENTER_LINE_UTC'] = str(t_center * 24. * 60. * 60.)
+    key = 'SC_clock_start'
+    if key in prm_dict_in.keys():
+        dt_start = float(prm_dict['SC_clock_start'])
+        dt_stop = float(prm_dict['SC_clock_stop'])
+        dt_center = (dt_start + dt_stop) / 2.0
+        t_center = dt_center - int(dt_center)
+        prm_dict['CENTER_LINE_UTC'] = str(t_center * 24. * 60. * 60.)
 
     # SC_identity -> PLATFORM
-    prm_dict['PLATFORM'] = GMTSAR_SENSOR_ID2NAME[int(prm_dict['SC_identity'])]
+    key = 'SC_identity'
+    if key in prm_dict_in.keys():
+        prm_dict['PLATFORM'] = GMTSAR_SENSOR_ID2NAME[int(prm_dict[key])]
 
     return prm_dict