Add qFSP boundary mask to RSLC

[bhawkins]

This PR implements the inputDataExceptionMask in RSLC products for the LSAR qFSP-related exception codes. It handles all six possible qFSP exception codes. For now, the strategy to is locate the peaks of the AC table weights in the EL angle domain and use the EL-angle LUT to generate the mask. This mask is in the raw data domain, so it's resampled to the RSLC grid using reskew LUTs. (These could be used to reskew other tables in some future PR, too). I added a vectorized LUT2d::eval overload to make this faster.

Eyeballing the plots for the case I tested on, I'm not sure the mask covers everything where there's obvious residual phase. So maybe instead of defining the overlap region as peak-to-peak, we should be more conservative and use a -6 dB threshold or something. I hope folks can do some InSAR tests to help figure out the best approach.

Note that the mask is populated based on the contents of the input L0B hasInputDataException flag, so that must be populated to see any effect.

Another question is what to do about mixed-mode frames where one L0B has a qFSP slip and its neighbor doesn't. For now, the qFSP overlap region is marked invalid for the entirety of the output product.

[bhawkins]

Only got part of the way through this PR in our meeting today. Comments so far:

[bhawkins]

Suggested change

	method: str
	method: str, optional

[bhawkins]

Suggested change

	b_error: bool
	b_error: bool, optional

[bhawkins]

Need to think about the interaction with EAP on/off.

[rad-eng-59]

duplicated const?

Suggested change

	.def("eval", py::overload_cast<double,const const_vec_t&>(&LUT2d<T>::eval, py::const_))
	.def("eval", py::overload_cast<double, const_vec_t&>(&LUT2d<T>::eval, py::const_))

[rad-eng-59]

Suggested change

	Enable LUT2d bounds error checking
	Enable LUT2d bounds error checking. Defaults to True.

[rad-eng-59]

Suggested change

	LUT2d interpolation method
	LUT2d interpolation method. Defaults to "bilinear".

[rad-eng-59]

FYI, L0B processor is using the same integer values for the same purpose for the first 6 fields but with more concise names (see below). Given our L0B process does not process S-SAR, it does not need to cover new fields. However, for the sake of consistency between names, we should perhaps request a change to L-SAR L0B to use the same dataclass. Here is the similar class in the current L0B process:

class QfspOutlierId(Flag):
    """NISAR L-band qFSP outlier identifier w/ bitwise operation"""
    NA = 0
    H0 = auto()
    H1 = auto()
    H2 = auto()
    V0 = auto()
    V1 = auto()
    V2 = auto()

Btw, for bitwise enum.Flag, the auto() will automatically generates the power of 2 values in the ascending order starting from 2^0.

[rad-eng-59]

As discussed in the meeting, you can use Antenna pattern HDF5 product whom used to generate AC table in instrument HDF5. The respective antenna parser will have some very useful methods. For instance, to get EL angle of the peak for all beams and their common AZ boresight angle, AntennaParser has this method handy:

el_peaks, az_boresight = AntennaParser(hdf5file).locate_beams_peak(pol)

FYI, regardless of the EL angle resolution of the patterns, the actual peak locations are locally and precisely estimated in this antenna method. AC table have a EL angle resolution of 50 mdeg.

[rad-eng-59]

Not sure why we need to use S-SARor even RESERVED given they are not properly being handled.

[rad-eng-59]

This can be any of three possibilities rather than NO_ANOMALY.
I would use anomaly_code as it is being passed by L0B process which for L-SAR it will automatically be 0 when there is no qFSP issue while it preserves the value for any other issue down the line to be handled accordingly in the future. Otherwise, I don't see the point of defining any other anomalies than qFSP in the respective enum.
That being said:

Suggested change

	if len(boundaries) == 0:
	for block_start in range(0, nt, block_size):
	block = slice(block_start, min(block_start + block_size, nt))
	nb = block.stop - block.start
	buf = np.zeros((nb, dataset.shape[1]), dataset.dtype)
	buf[...] = AnomalyCode.NO_ANOMALY.value
	write_block(buf, np.s_[block, :])
	if len(boundaries) == 0:
	for block_start in range(0, nt, block_size):
	block = slice(block_start, min(block_start + block_size, nt))
	nb = block.stop - block.start
	buf = np.zeros((nb, dataset.shape[1]), dataset.dtype)
	buf[...] = AnomalyCode(anomaly_code).value
	write_block(buf, np.s_[block, :])

[rad-eng-59]

Suggested change

	"""
	Notes
	-------
	This function generates invalid mask simply for 12-channel L-SAR product with qFSP sample slip anomaly.
	"""

[rad-eng-59]

Suggested change

	Determine EL angle intervals associated with NISAR anomaly codes.
	Determine EL angle intervals covering qFSP transition regions of 12-channel (three qFSPs) L-band NISAR associated with qFSP sample slip anomaly codes.

[rad-eng-59]

Perhaps it is worth checking the size of the arrays prior to slicing assuming 12 channels.

Suggested change

	# (start, end) EL angles between beam x and y peaks
	# (start, end) EL angles between beam x and y peaks
	if (peak_angles['H'].size != 12 or peak_angles['V'].size != 12):
	raise ValueError(f'Number of channels for H/V is {peak_angles['H'].size}/{peak_angles['V'].size} instead of 12 expected for L-SAR NISAR!')

[rad-eng-59]

Perhaps one can check for EAP and if it is OFF issue a warning that the mask values can be invalid due to EAP=OFF.
I suggest we simply generate a qFSP sample-slip mask when EAP=True which also guarantees that both antenna and instrument HDF5 are available. In case of EAP=False, a warning is issued w/ empty dataset.

[rad-eng-59]

Suggested change

	mask_chunk = np.zeros((nb, nr), dataset.dtype)
	mask_chunk = np.full(fill_value=AnomalyCode.NO_ANOMLAY.value, shape=(nb, nr), dtype=dataset.dtype)