add `los2slope` to project LOS displacement to the downslope component

[ashokdahal]

Description of proposed changes

Liine-of-Sight (LoS) displacement to the downslope component with reference to issue #1170 :

This code was developed with a particular focus on the landslide/slope deformation community. The downslope projection is performed by defining the satellite azimuth unit vector and the hillslope azimuth unit vector then projecting the LoS onto the slope using the dot product. This then leads to a “scaling factor” where the conversion to Displacement_Downslope = Displacement_LoS * Scaling Factor. The Python scripts will execute, but we request a full review of the equations to ensure the output is correct. One challenge we faced is that due to different conventions used, e.g., sometimes 0 is north, sometimes 0 is east, sometimes positive clockwise and sometimes positive anticlockwise, the literature is full of a mix of cosine and sine functions when performing these projections.

The code uses MintPy data as inputs to project the LoS deformation onto the downslope direction. The code used the existing code asc_desc2horz_vert.py as a starting point. The main new added functions are median_filter, smooth_dem, get_slp_asp, and get_design_matrix4slope. The median_filter filters the existing digital elevation model into a less-noisy version, and its kernel size is controlled via input parameter “-m” which defaults to 25 pixels. This filter helps reduce large downslope scaling factors that result from noise in the DEM. The smooth_dem can be optionally used instead of median_filter in case of speckle-like noise where few pixels have extremely small or large values, which is not applied by default and can be used by using the “-si” parameter. The get_slp_asp function calculates and saves hillslope angle (slope) and hillslope aspect (aspect) as geotiff files using gdal (we used gdal instead of save_gdal util because the gdal function that calculates slope and aspect automatically saves the data as .tif, so it was easier to save on the fly than using save_gdal). The get_design_matrix4slope is where the downslope projection factor (“scaling factor”) is calculated based on Handwerger et al. (2019; https://www.nature.com/articles/s41598-018-38300-0#Sec4) to match the same convention; the aspect is converted to the anti-clockwise direction and heading angle is measured from the north. A full review of the equations and the codes would be greatly appreciated.

To test and run the function, please use the command; the test dataset provided is attached here: SampleData.zip

To test the code, please run: python los2slope.py -file ./T122_ASC/geo_velocity_msk.h5 -g ./T122_ASC/geo_geometryRadar.h5 -o ./T122_ASC/geo_velocityDownslope.h5 -m 15 --slp_thresh 5.0 --scaling_factor_thresh 5

For further review/discussion on this as well as review of the formula could @yunjunz, @taliboliver, @mgovorcin, @EJFielding and @alhandwerger provide some feedback?

[welcome[bot]]

💖 Thanks for opening this pull request! Please check out our contributing guidelines. 💖 Keep in mind that all new features should be documented. It helps to write the comments next to the code or below your functions describing all arguments, and return types before writing the code. This will help you think about your code design and usually results in better code.

[alhandwerger]

@forrestfwilliams

[yunjunz]

@taliboliver @mgovorcin Could you take a look at the PR when you get a chance please? Here are a few things to check after a quick look:

1. The angle convention is defined in mintpy.utils.utils0.
2. As for the equation, having a very simple unit test in python shown in the PR comments, or even better in a small script, such as here https://github.com/insarlab/MintPy/tree/main/tests, would be very helpful.

@ashokdahal Thank you for the PR! Here is a guide for adding a new executable script in mintpy. I believe a few things are missing in this PR.

[taliboliver]

@taliboliver @mgovorcin Could you take a look at the PR when you get a chance please? Here are a few things to check after a quick look:

1. The angle convention is defined in mintpy.utils.utils0.
2. As for the equation, having a very simple unit test in python shown in the PR comments, or even better in a small script, such as here https://github.com/insarlab/MintPy/tree/main/tests, would be very helpful.

@ashokdahal Thank you for the PR! Here is a guide for adding a new executable script in mintpy. I believe a few things are missing in this PR.

Hi @yunjunz sounds good, I'll try to take a look at it in the coming days.