(RSLC) Clarify `validSamplesSubSwath*` Description and Indexing Convention?

Related to https://github.com/isce-framework/isce3/pull/327

Summary

The RSLC validSamplesSubSwath* dataset descriptions are ambiguous about their indexing convention and boundary semantics.

Let's clarify what the current behavior is, and draft a new description?

Current Dataset Description:

"First and last valid sample in each line of {nth} subswath"

Ambiguities:

1. Is indexing zero-based or one-based?
2. Is "last valid sample" inclusive or exclusive?
   • To me, "last valid sample" reads as being inclusive.
3. What does [0, 0] represent?
   • Does [0, 0] represent "all invalid" vs "sample 0 valid" ?
   • Per https://github.com/isce-framework/isce3/pull/327, [0, 0] is an expected occurrence.

Current Behavior (?)

Per Claude's analysis of ISCE3, the current behavior of validSamplesSubSwath* seems to be:

• Zero-indexed: First valid sample can be 0 (not 1)
• Half-open interval [start, end): Column 0 is inclusive, column 1 is exclusive
• Invalid line indicator: When start >= end (e.g., [0, 0]), the azimuth line has no valid samples

@bhawkins , is this a correct assessment?

Brainstorming

Assuming Claude's assessment is correct, to start the discussion, here are a couple of ideas to clarify the description:

Option A:

Zero-indexed Begin and end indices for valid range samples in each azimuth line of {nth}
subswath. Column 0 contains the first valid sample (inclusive);
column 1 contains one-past-the-last valid sample (exclusive). The special case
[0,0] (or any row with identical values) indicates no valid samples for that
azimuth line

Option B:

Valid range samples for each azimuth line of {nth} subswath, stored as a
two-column array. Column 0 contains the zero-indexed first valid sample
(inclusive); column 1 contains one-past-the-last valid sample (exclusive).
When both values are equal (e.g., [0,0]), that azimuth line contains
no valid samples

Importance

This clarification is important because:

• Downstream users need to know whether [0, 0] represents "all invalid" vs "sample 0 valid"
• Ambiguous descriptions can lead to off-by-one errors in external tooling

cc: @hfattahi @bhawkins

cc downsteam products leads, to ensure the logic in their workflows are consistent with the updated description:
@gshiroma @xhuang-jpl @seongsujeong @jungkyoJung

Start by reviewing PR #327 and the current RSLC validSamplesSubSwath* dataset descriptions and behavior. Confirm the zero-based, half-open indexing and the meaning of equal values such as [0,0], then update the description so these conventions and the invalid-line case are explicit. Done means downstream users can interpret every row without ambiguity.