DAS-2361 - Update comments and names to be clearer

Author: sudha-murthy

CHANGELOG.md

@@ -1,8 +1,10 @@
 ## v1.1.9
-### 2025-08-07
+### 2025-08-013
 
-This version of HOSS updates fixes invalid output extents for whole earth
-spatial subset requests on Polar grids.
+This version of HOSS updates fixes invalid output extents in cases where the
+requested bounding area (bbox, shape) extends beyond valid locations for the native
+projection of the data. E.g., EASE-GRID-2 North Polar (LAEA) projection becomes INF
+at latitude -90°.
 
 ## v1.1.8
 ### 2025-05-23

hoss/projection_utilities.py

@@ -203,20 +203,25 @@ def get_projected_x_y_extents(
     grid_lats, grid_lons = get_grid_lat_lons(  # pylint: disable=unpacking-non-sequence
         x_values, y_values, crs
     )
-
+    # When projected, the perimeter of a bounding box or polygon in geographic
+    # terms will become curved.  To determine the X, Y extent of the requested
+    # bounding area, we need a perimeter with a suitable density of points, such that
+    # we catch that curve when projected. The source file resolution is used to define
+    # the necessary number of points (density).
     geographic_resolution = get_geographic_resolution(grid_lons, grid_lats)
-    points_in_requested_extent = get_resolved_geojson(
+    densified_perimeter = get_densified_perimeter(
         geographic_resolution, shape_file=shape_file, bounding_box=bounding_box
     )
 
-    # get the extent of the granule.
+    # To avoid out-of-limits projection, we need to clip the bounding perimeter to
+    # the source file's geographic extents
     granule_extent = BBox(
         np.min(grid_lons), np.min(grid_lats), np.max(grid_lons), np.max(grid_lats)
     )
 
-    clipped_points = get_filtered_points(points_in_requested_extent, granule_extent)
+    clipped_perimeter = get_filtered_points(densified_perimeter, granule_extent)
 
-    return get_x_y_extents_from_geographic_points(clipped_points, crs)
+    return get_x_y_extents_from_geographic_points(clipped_perimeter, crs)
 
 
 def get_filtered_points(
@@ -266,7 +271,7 @@ def get_geographic_resolution(longitudes: np.ndarray, latitudes: np.ndarray) ->
     return np.nanmin(np.sqrt(np.add(lon_square_diffs, lat_square_diffs)))
 
 
-def get_resolved_geojson(
+def get_densified_perimeter(
     resolution: float, shape_file: str = None, bounding_box: BBox = None
 ) -> List[Coordinates]:
     """Take a shape file or bounding box, as defined by the input Harmony

tests/unit/test_projection_utilities.py

@@ -27,6 +27,7 @@
 )
 from hoss.projection_utilities import (
     get_bbox_polygon,
+    get_densified_perimeter,
     get_filtered_points,
     get_geographic_resolution,
     get_grid_lat_lons,
@@ -36,7 +37,6 @@
     get_projected_x_y_variables,
     get_resolved_feature,
     get_resolved_features,
-    get_resolved_geojson,
     get_resolved_geometry,
     get_resolved_line,
     get_variable_crs,
@@ -718,7 +718,7 @@ def test_get_geographic_resolution(self):
     @patch('hoss.projection_utilities.get_bbox_polygon')
     @patch('hoss.projection_utilities.get_resolved_feature')
     @patch('hoss.projection_utilities.get_resolved_features')
-    def test_get_resolved_geojson(
+    def test_get_densified_perimeter(
         self,
         mock_get_resolved_features,
         mock_get_resolved_feature,
@@ -747,7 +747,7 @@ def test_get_resolved_geojson(
 
         with self.subTest('Shape file is specified and used'):
             self.assertListEqual(
-                get_resolved_geojson(resolution, shape_file=shape_file),
+                get_densified_perimeter(resolution, shape_file=shape_file),
                 resolved_features,
             )
             mock_get_resolved_features.assert_called_once_with(
@@ -760,7 +760,7 @@ def test_get_resolved_geojson(
 
         with self.subTest('Bounding box is specified and used'):
             self.assertListEqual(
-                get_resolved_geojson(resolution, bounding_box=bounding_box),
+                get_densified_perimeter(resolution, bounding_box=bounding_box),
                 resolved_feature,
             )
             mock_get_resolved_features.assert_not_called()
@@ -774,7 +774,7 @@ def test_get_resolved_geojson(
 
         with self.subTest('Bounding box is used when both are specified'):
             self.assertListEqual(
-                get_resolved_geojson(
+                get_densified_perimeter(
                     resolution, shape_file=shape_file, bounding_box=bounding_box
                 ),
                 resolved_feature,
@@ -789,7 +789,7 @@ def test_get_resolved_geojson(
 
         with self.subTest('Neither shape file nor bbox, raises exception'):
             with self.assertRaises(MissingSpatialSubsetInformation):
-                get_resolved_geojson(resolution, None, None)
+                get_densified_perimeter(resolution, None, None)
                 mock_get_resolved_features.assert_not_called()
                 mock_get_bbox_polygon.assert_not_called()
                 mock_get_resolved_feature.assert_not_called()