(Caltools) Report Corner Reflector Incidence Angle in Point Target Analysis

[Tyler-g-hudson]

Action

Interpolate and acquire the incidence angle for each corner reflector from the input HDF5 during Point Target Analysis and include this information in the QA STATS HDF5 colocated with the other PTA info for the corner reflectors.

Products

This is most important for RSLC but may be included in GSLC point target analysis if possible.

Reason

Downstream atmospheric (tropo/iono) range delay corrections make use of incidence angle to calculate the length that the radar beam passes through a given atmospheric layer. It is possible to calculate this value using an orbit file and the CR LLH, but I'm told it can more easily be acquired using a metadata cube in the RSLC source product.

Notes

The most appropriate place to acquire this value is likely within the PTA workflow in ISCE3, and therefore this will likely require a separate ISCE3 pull request to complete. If this is done, there will be no additional inputs required by nisarqa, as the inputs required for this output are already present within that workflow.

Acquisition Process

TBD, I'm told interpolating over the metadata cubes is simple though.

[nemo794]

Thanks for raising this Issue, @Tyler-g-hudson !

Some questions/clarifications:

• Is this the LUT in the RSLC to be interpolated? "/science/LSAR/RSLC/metadata/geolocationGrid/incidenceAngle"
• To confirm, the only inputs required are the (1) RSLC HDF5 and (2) Corner Reflector CSV? (No additional external files?)
  • If so, great! These two files are already inputs to RSLC PTA and GSLC PTA
• For interpolating the metadata cubes, a DEM is required. However, currently the DEM is not a required input to RSLC QA, and it is only optional for GSLC QA. QA could interpolate using a zero-height DEM (in which case no additional input is required), but should double-check if that would provide sufficient accuracy required for this task. If not, then nisarqa RSLC QA and GSLC QA would need an additional required input of the DEM when running this workflow.

[nemo794]

For future reference:

• nisarqa does not currently have an implementation for interpolating the metadata cubes.
• However, an interpolator was initially implemented during development of a different PR (but later removed in favor of a faster method).
  • Here is the PR branch, with the complete commit history: main...nemo794:nisarqa:bugfix_goff_quiver
  • Here is the specific commit with the interpolator added (it might have been updated in a later commit?): e9f6408
  • Here is the specific commit where the interpolator was removed: 0d3a41c

Warning

During testing, it took ~1.2 sec to construct the interpolator, vs. ~0.0001 sec to interpolate each point. So, it is recommended to pass in entire arrays to be interpolated. (In other words, please do not pass in individual points one-by-one to the function.)

Interpolator function, in src/nisarqa/utils/utils.py:

from scipy.interpolate import RegularGridInterpolator

def interpolate_points_in_metadata_cube(
    data: np.ndarray,
    height_coordinates: np.ndarray,
    y_coordinates: np.ndarray,
    x_coordinates: np.ndarray,
    h_vals_of_points: np.ndarray,
    y_vals_of_points: np.ndarray,
    x_vals_of_points: np.ndarray,
    method: str = "cubic",
) -> np.ndarray:
    """
    Interpolates value at (h, y, x) from a 3D data cube.

    Parameters
    ----------
    data : np.ndarray with shape (m,n,p)
        3D NumPy array representing the metadata cube.
        Note that for ease of use with GIS, metadata cubes are
        oriented in HDF5 with:
            axes 0 = height
            axes 1 = y coordinates
            axes 2 = x coordinates
    height_coordinates : np.ndarray with shape (m,)
        1D array of height values corresponding to the first axis of `data`.
    y_coordinates : np.ndarray with shape (n,)
        1D array of y-coordinates corresponding to the second axis of `data`.
    x_coordinates : np.ndarray with shape (p,)
        1D array of x-coordinates corresponding to the third axis of `data`.
    h_vals_of_points : np.ndarray with shape (n,p)
        Target height of each point to interpolate.
    y_vals_of_points : np.ndarray with shape (n,p)
        Target y-coordinate of each point to interpolate.
    x_vals_of_points : np.ndarray with shape (n,p)
        Target x-coordinate of each point to interpolate.
    method : str, optional
        Interpolation method. One of: "linear", "nearest", "slinear",
        "cubic", "quintic", or "pchip". Default is "cubic", which is the
        recommended interpolation method for NISAR metadata cubes per
        the NISAR L2 product specification documents.

    Returns
    -------
    interp_points : np.ndarray with shape (m,p)
        Interpolated value of `data` at each point (h, y, x).
    """
    log = nisarqa.get_logger()

    # The dimensions of `data` must match `height_coordinates`,
    # `y_coordinates`, and `x_coordinates`.
    if data.ndim != 3:
        log.error(f"{data.shape=}, must be a 3D array")
    if len(height_coordinates) != data.shape[0]:
        log.error(f"{len(height_coordinates)=}, must match {data.shape[0]=}")
    if len(y_coordinates) != data.shape[0]:
        log.error(f"{len(height_coordinates)=}, must match {data.shape[1]=}")
    if len(x_coordinates) != data.shape[0]:
        log.error(f"{len(height_coordinates)=}, must match {data.shape[2]=}")

    # There must be an h, y, and x value for each point to be interpolated.
    if not (
        h_vals_of_points.shape
        == y_vals_of_points.shape
        == x_vals_of_points.shape
    ):
        log.error(
            f"{h_vals_of_points.shape=}, {y_vals_of_points.shape=}, and"
            f" {x_vals_of_points.shape=}. They must all have the same shape."
        )

    # Note: during testing, it took ~1.2 sec to construct the interpolator,
    # vs. ~0.0001 sec to interpolate each point. So, it is preferred to pass in
    # entire arrays to be interpolated

    # Create an interpolator function
    interpolator = RegularGridInterpolator(
        (height_coordinates, y_coordinates, x_coordinates),
        data,
        method=method,
        bounds_error=False,
        fill_value=np.nan,
    )

    points = np.column_stack(
        (
            h_vals_of_points.ravel(),
            y_vals_of_points.ravel(),
            x_vals_of_points.ravel(),
        )
    )

    # Perform interpolation
    interpolated_values = interpolator(points)

    # Reshape the x the scalar values of the interpolated points
    return interpolated_values.reshape(x_vals_of_points.shape)

Usage, from src/nisarqa/processing/insar/quiver_plots.py in that commit:

    grd_trk_vel_at_arrow_tail = nisarqa.interpolate_points_in_metadata_cube(
        data=ground_track_velocity.data,  # the metadata LUT itself
        height_coordinates=ground_track_velocity.z_coord_vector,
        y_coordinates=ground_track_velocity.y_coord_vector,
        x_coordinates=ground_track_velocity.x_coord_vector,
        # assume zero-height again
        h_vals_of_points=np.zeros(
            (num_arrows_y_direction, num_arrows_x_direction)
        ),
        y_vals_of_points=Y_tail_vals_grid,
        x_vals_of_points=X_tail_vals_grid,
        method="cubic",  # GOFF Product Specs recommend "cubic"
    )