Related to #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:
- Is indexing zero-based or one-based?
- Is "last valid sample" inclusive or exclusive?
- To me, "last valid sample" reads as being inclusive.
- What does
[0, 0] represent?
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
Related to #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:
Ambiguities:
[0, 0]represent?[0, 0]represent "all invalid" vs "sample 0 valid" ?[0, 0]is an expected occurrence.Current Behavior (?)
Per Claude's analysis of ISCE3, the current behavior of
validSamplesSubSwath*seems to be:0(not1)[start, end): Column 0 is inclusive, column 1 is exclusivestart >= 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:
Option B:
Importance
This clarification is important because:
[0, 0]represents "all invalid" vs "sample 0 valid"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