allow az_step/rg_step arguments to as_isce3_radargrid (#102)

* allow az_step/rg_step arguments to `as_isce3_radargrid`

This allows a more coarse radar grid, as needed by some lookup tables such as the SET correction

* Apply PRF suggestions from code review

Co-authored-by: Heresh Fattahi <hersh.fattahi@gmail.com>

* adjust length/width based on az_step/rg_step

* fix the logic for width/length calculation with rg/az_step

* reversed order of length/width

* add two tests for as_isce3_radar_grid

fixed the division to make the tests pass

* add clarification to docstring about sensing start

---------

Co-authored-by: Heresh Fattahi <hersh.fattahi@gmail.com>

src/s1reader/s1_burst_slc.py

@@ -2,6 +2,7 @@
 from dataclasses import dataclass
 import datetime
 import tempfile
+from typing import Optional
 import warnings
 from packaging import version
 
@@ -263,18 +264,54 @@ def __str__(self):
     def __repr__(self):
         return f"{self.__class__.__name__}(burst_id={self.burst_id})"
 
-    def as_isce3_radargrid(self):
+    def as_isce3_radargrid(self,
+                           az_step: Optional[float] = None,
+                           rg_step: Optional[float] = None):
         '''Init and return isce3.product.RadarGridParameters.
 
-        Returns:
-        --------
+        The `az_step` and `rg_step` parameters are used to construct a
+        decimated grid. If not specified, the grid will be at the full radar
+        resolution.
+        Note that increasing the range/azimuth step size does not change the sensing
+        start of the grid, as the grid is decimated rather than multilooked.
+
+        Parameters
+        ----------
+        az_step : float, optional
+            Azimuth step size in seconds. If not provided, the azimuth step
+            size is set to the azimuth time interval.
+        rg_step : float, optional
+            Range step size in meters. If not provided, the range step size
+            is set to the range pixel spacing.
+
+        Returns
+        -------
         _ : RadarGridParameters
             RadarGridParameters constructed from class members.
         '''
 
-        prf = 1 / self.azimuth_time_interval
-
         length, width = self.shape
+        if az_step is None:
+            az_step = self.azimuth_time_interval
+        else:
+            if az_step < 0:
+                raise ValueError("az_step cannot be negative")
+            length_in_seconds = length * self.azimuth_time_interval
+            if az_step > length_in_seconds:
+                raise ValueError("az_step cannot be larger than radar grid")
+            length = int(length_in_seconds / az_step)
+
+        if rg_step is None:
+            rg_step = self.range_pixel_spacing
+        else:
+            if rg_step < 0:
+                raise ValueError("rg_step cannot be negative")
+            width_in_meters = width * self.range_pixel_spacing
+            if rg_step > width_in_meters:
+                raise ValueError("rg_step cannot be larger than radar grid")
+            width = int(width_in_meters / rg_step)
+
+        prf = 1 / az_step
 
         time_delta = datetime.timedelta(days=2)
         ref_epoch = isce3.core.DateTime(self.sensing_start - time_delta)
@@ -286,7 +323,7 @@ def as_isce3_radargrid(self):
                                                  self.wavelength,
                                                  prf,
                                                  self.starting_range,
-                                                 self.range_pixel_spacing,
+                                                 rg_step,
                                                  isce3.core.LookSide.Right,
                                                  length,
                                                  width,

tests/test_bursts.py

@@ -1,7 +1,10 @@
+from datetime import timedelta
+
 import isce3
 import numpy as np
 
 
+
 def test_burst(bursts):
     last_valid_lines = [1487, 1489, 1489, 1490, 1487, 1488, 1488, 1489, 1488]
     first_valid_lines = [28, 27, 27, 27, 28, 28, 28, 27, 28]
@@ -72,3 +75,39 @@ def test_burst(bursts):
         assert burst.azimuth_fm_rate.mean == 901673.89084624
         assert burst.azimuth_fm_rate.std == 149896229.0
         assert burst.azimuth_fm_rate.coeffs == az_fm_rate_poly1d_coeffs[i]
+
+
+def test_as_isce3_radargrid(bursts):
+    for burst in bursts:
+        grid = burst.as_isce3_radargrid()
+        assert grid.width == burst.width
+        assert grid.length == burst.length
+        assert grid.starting_range == burst.starting_range
+        dt = isce3.core.DateTime((burst.sensing_start - timedelta(days=2)))
+        assert dt == grid.ref_epoch
+        assert grid.prf == 1 / burst.azimuth_time_interval
+        assert grid.range_pixel_spacing == burst.range_pixel_spacing
+        assert str(grid.lookside) == 'LookSide.Right'
+        assert grid.wavelength == burst.wavelength
+
+
+def test_as_isce3_radargrid_step_change(bursts):
+    # Change the az_step, rg_step in .as_isce3_radargrid()
+    burst = bursts[0]
+    rg_step = burst.range_pixel_spacing
+    az_step = burst.azimuth_time_interval
+    grid = burst.as_isce3_radargrid(az_step=az_step, rg_step=rg_step)
+    assert grid.width == burst.width
+    assert grid.length == burst.length
+    assert grid.prf == 1 / az_step
+
+
+    rg_step *= 2
+    grid = burst.as_isce3_radargrid(rg_step=rg_step)
+    assert grid.width == burst.width // 2
+    assert grid.length == burst.length
+
+    az_step *= 2
+    grid = burst.as_isce3_radargrid(az_step=az_step)
+    assert grid.width == burst.width
+    assert grid.length == burst.length // 2