Add optional metadata to Pyresample 2.0 AreaDefinition

pyresample/area_config.py

@@ -76,7 +76,7 @@ def load_area(area_file_name, *regions):
 
     Returns
     -------
-    area_defs : AreaDefinition or list
+    area_defs : pyresample.geometry.AreaDefinition or list
         If one area name is specified a single AreaDefinition object is returned.
         If several area names are specified a list of AreaDefinition objects is returned
 
@@ -109,7 +109,7 @@ def load_area_from_string(area_strs, *regions):
 
     Returns
     -------
-    area_defs : AreaDefinition or list
+    area_defs : pyresample.geometry.AreaDefinition or list
         If one area name is specified a single AreaDefinition object is returned.
         If several area names are specified a list of AreaDefinition objects is returned
     """
@@ -376,7 +376,7 @@ def get_area_def(area_id, area_name, proj_id, proj4_args, width, height, area_ex
         Number of pixel in y dimension
     rotation: float
         Rotation in degrees (negative is cw)
-    area_extent : list
+    area_extent : list | tuple
         Area extent as a list of ints (LL_x, LL_y, UR_x, UR_y)
 
     Returns
@@ -458,7 +458,7 @@ def create_area_def(area_id, projection, width=None, height=None, area_extent=No
 
     Returns
     -------
-    AreaDefinition or DynamicAreaDefinition : AreaDefinition or DynamicAreaDefinition
+    area : pyresample.geometry.AreaDefinition or pyresample.geometry.DynamicAreaDefinition
         If shape and area_extent are found, an AreaDefinition object is returned.
         If only shape or area_extent can be found, a DynamicAreaDefinition object is returned
 

pyresample/ewa/ewa.py

@@ -31,9 +31,9 @@ def ll2cr(swath_def, area_def, fill=np.nan, copy=True):
 
     Parameters
     ----------
-    swath_def : SwathDefinition
+    swath_def : pyresample.geometry.SwathDefinition
         Navigation definition for swath data to remap
-    area_def : AreaDefinition
+    area_def : pyresample.geometry.AreaDefinition
         Grid definition to be mapped to
     fill : float, optional
         Fill value used in longitude and latitude arrays
@@ -95,7 +95,7 @@ def fornav(cols, rows, area_def, data_in,
         Column location for each input swath pixel (from `ll2cr`)
     rows : numpy array
         Row location for each input swath pixel (from `ll2cr`)
-    area_def : AreaDefinition
+    area_def : pyresample.geometry.AreaDefinition
         Grid definition to be mapped to
     data_in : numpy array or tuple of numpy arrays
         Swath data to be remapped to output grid

pyresample/future/geometry/__init__.py

@@ -20,6 +20,7 @@
 from typing import Union
 
 from .area import AreaDefinition, DynamicAreaDefinition  # noqa
+from .base import BaseDefinition  # noqa
 from .swath import CoordinateDefinition, SwathDefinition  # noqa
 
 StaticGeometry = Union[SwathDefinition, CoordinateDefinition, AreaDefinition]

pyresample/future/geometry/area.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 #
-# Copyright (c) 2021 Pyresample developers
+# Copyright (c) 2021-2022 Pyresample developers
 #
 # This program is free software: you can redistribute it and/or modify it under
 # the terms of the GNU Lesser General Public License as published by the Free
@@ -19,4 +19,106 @@
 
 from __future__ import annotations
 
-from pyresample.geometry import AreaDefinition, DynamicAreaDefinition  # noqa
+from typing import Optional, Union
+
+from pyproj import CRS
+
+from pyresample.geometry import AreaDefinition as LegacyAreaDefinition  # noqa
+from pyresample.geometry import (  # noqa
+    DynamicAreaDefinition,
+    get_full_geostationary_bounding_box_in_proj_coords,
+    get_geostationary_angle_extent,
+    get_geostationary_bounding_box_in_lonlats,
+    get_geostationary_bounding_box_in_proj_coords,
+)
+
+
+class AreaDefinition(LegacyAreaDefinition):
+    """Uniformly-spaced grid of pixels on a coordinate referenced system.
+
+    Args:
+        crs:
+            Dictionary of PROJ parameters or string of PROJ or WKT parameters.
+            Can also be a :class:`pyproj.crs.CRS` object.
+        width:
+            x dimension in number of pixels, aka number of grid columns
+        height:
+            y dimension in number of pixels, aka number of grid rows
+        area_extent:
+            Area extent as a list (lower_left_x, lower_left_y, upper_right_x, upper_right_y)
+        attrs:
+            Arbitrary metadata related to the area. Some keys in this
+            dictionary have special meaning and may be used for various
+            logging or serialization processes. The primary special keys are:
+
+            * name: The identifying name for this area. This is equivalent
+                to 'area_id' in the legacy AreaDefinition class. It is used
+                in YAML serialization if provided. Defaults to an empty string
+                if not provided. Not providing this should not affect normal
+                coordinate operations.
+            * description: A human-readable description of the area. This is
+                equivalent to 'description' in the legacy AreaDefinition class.
+                It is used in YAML serialization if provided.
+
+    Attributes:
+        area_id (str):
+            Identifier for the area. This is a convenience for backwards
+            compatibility and accesses the ``.attrs['name']`` metadata.
+            This will be set to an empty string if not provided.
+        width (int):
+            x dimension in number of pixels, aka number of grid columns
+        height (int):
+            y dimension in number of pixels, aka number of grid rows
+        size (int):
+            Number of points in grid
+        area_extent_ll (tuple):
+            Area extent in lons lats as a tuple (lower_left_lon, lower_left_lat, upper_right_lon, upper_right_lat)
+        pixel_size_x (float):
+            Pixel width in projection units
+        pixel_size_y (float):
+            Pixel height in projection units
+        upper_left_extent (tuple):
+            Coordinates (x, y) of upper left corner of upper left pixel in projection units
+        pixel_upper_left (tuple):
+            Coordinates (x, y) of center of upper left pixel in projection units
+        pixel_offset_x (float):
+            x offset between projection center and upper left corner of upper
+            left pixel in units of pixels.
+        pixel_offset_y (float):
+            y offset between projection center and upper left corner of upper
+            left pixel in units of pixels.
+        crs (CRS):
+            Coordinate reference system object similar to the PROJ parameters in
+            `proj_dict` and `proj_str`. This is the preferred attribute to use
+            when working with the `pyproj` library. Note, however, that this
+            object is not thread-safe and should not be passed between threads.
+        attrs (dict):
+            Arbitrary metadata related to the area.
+
+    """
+
+    def __init__(
+            self,
+            crs: Union[str, int, dict, CRS],
+            width: int,
+            height: int,
+            area_extent: tuple[float, float, float, float],
+            attrs: Optional[dict] = None
+    ):
+        # FUTURE: Maybe do `shape` instead of the separate height and width
+        # FUTURE: Add 'to_legacy()' method
+        # FUTURE: Add __slots__
+        # FUTURE: Convert this to new class that uses a legacy area internally
+        #         Use this to more easily deprecate usage of old properties
+        attrs = attrs or {}
+        area_id = attrs.get("name", "")
+        super().__init__(
+            area_id,
+            "",
+            area_id,
+            crs,
+            width,
+            height,
+            area_extent,
+        )
+        self.attrs = attrs

pyresample/future/geometry/base.py

@@ -0,0 +1,17 @@
+# Copyright (c) 2021-2022 Pyresample developers
+#
+# This program is free software: you can redistribute it and/or modify it under
+# the terms of the GNU Lesser General Public License as published by the Free
+# Software Foundation, either version 3 of the License, or (at your option) any
+# later version.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more
+# details.
+#
+# You should have received a copy of the GNU Lesser General Public License along
+# with this program.  If not, see <http://www.gnu.org/licenses/>.
+"""Base geometry definitions and utility functions."""
+
+from pyresample.geometry import BaseDefinition, get_array_hashable  # noqa

pyresample/test/conftest.py

@@ -28,6 +28,8 @@
     CoordinateDefinition,
     SwathDefinition,
 )
+from pyresample.geometry import AreaDefinition as LegacyAreaDefinition
+from pyresample.geometry import SwathDefinition as LegacySwathDefinition
 from pyresample.test.utils import create_test_latitude, create_test_longitude
 
 SRC_SWATH_2D_SHAPE = (50, 10)
@@ -36,6 +38,67 @@
 DST_AREA_SHAPE = (80, 85)
 
 
+@pytest.fixture(params=[LegacySwathDefinition, SwathDefinition],
+                ids=["LegacySwathDefinition", "SwathDefinition"])
+def swath_class(request):
+    """Get one of the currently active 'SwathDefinition' classes.
+
+    Currently only includes the legacy 'SwathDefinition' class and the future
+    'SwathDefinition' class in 'pyresample.future.geometry.swath'.
+
+    """
+    return request.param
+
+
+@pytest.fixture
+def create_test_swath(swath_class):
+    """Get a function for creating SwathDefinitions for testing.
+
+    Should be used as a pytest fixture and will automatically run the test
+    function with the legacy SwathDefinition class and the future
+    SwathDefinition class. If tests require a specific class they should
+    NOT use this fixture and instead use the exact class directly.
+
+    """
+    def _create_test_swath(lons, lats, **kwargs):
+        return swath_class(lons, lats, **kwargs)
+    return _create_test_swath
+
+
+@pytest.fixture(params=[LegacyAreaDefinition, AreaDefinition],
+                ids=["LegacyAreaDefinition", "AreaDefinition"])
+def area_class(request):
+    """Get one of the currently active 'AreaDefinition' classes.
+
+    Currently only includes the legacy 'AreaDefinition' class and the future
+    'AreaDefinition' class in 'pyresample.future.geometry.area'.
+
+    """
+    return request.param
+
+
+@pytest.fixture
+def create_test_area(area_class):
+    """Get a function for creating AreaDefinitions for testing.
+
+    Should be used as a pytest fixture and will automatically run the test
+    function with the legacy AreaDefinition class and the future
+    AreaDefinition class. If tests require a specific class they should
+    NOT use this fixture and instead use the exact class directly.
+
+    """
+    def _create_test_area(crs, width, height, area_extent, **kwargs):
+        """Create an AreaDefinition object for testing."""
+        args = (crs, width, height, area_extent)
+        if area_class is LegacyAreaDefinition:
+            attrs = kwargs.pop("attrs", {})
+            area_id = attrs.pop("name", "test_area")
+            args = (area_id, "", "") + args
+        area = area_class(*args, **kwargs)
+        return area
+    return _create_test_area
+
+
 def _euro_lonlats():
     lons = create_test_longitude(3.0, 12.0, SRC_SWATH_2D_SHAPE)
     lats = create_test_latitude(75.0, 26.0, SRC_SWATH_2D_SHAPE)
@@ -117,8 +180,7 @@ def area_def_lcc_conus_1km():
     """Create an AreaDefinition with an LCC projection over CONUS (1500, 2000)."""
     proj_str = "+proj=lcc +lon_0=-95 +lat_1=35.0 +lat_2=35.0 +datum=WGS84 +no_defs"
     crs = CRS.from_string(proj_str)
-    area_def = AreaDefinition("area_def_lcc_conus", "", "",
-                              crs, SRC_AREA_SHAPE[1], SRC_AREA_SHAPE[0],
+    area_def = AreaDefinition(crs, SRC_AREA_SHAPE[1], SRC_AREA_SHAPE[0],
                               (-750000, -750000, 750000, 750000))
     return area_def
 
@@ -131,7 +193,6 @@ def area_def_stere_source():
 
     """
     return AreaDefinition(
-        'areaD', 'Europe (3km, HRV, VTC)', 'areaD',
         {
             'a': '6378144.0',
             'b': '6356759.0',
@@ -141,15 +202,14 @@ def area_def_stere_source():
             'proj': 'stere'
         },
         SRC_AREA_SHAPE[1], SRC_AREA_SHAPE[0],
-        [-1370912.72, -909968.64000000001, 1029087.28, 1490031.3600000001]
+        (-1370912.72, -909968.64000000001, 1029087.28, 1490031.3600000001),
     )
 
 
 @pytest.fixture(scope="session")
 def area_def_stere_target():
     """Create an AreaDefinition with a polar-stereographic projection (800, 850)."""
     return AreaDefinition(
-        'areaD', 'Europe (3km, HRV, VTC)', 'areaD',
         {
             'a': '6378144.0',
             'b': '6356759.0',
@@ -159,23 +219,22 @@ def area_def_stere_target():
             'proj': 'stere'
         },
         DST_AREA_SHAPE[1], DST_AREA_SHAPE[0],
-        [-1370912.72, -909968.64000000001, 1029087.28, 1490031.3600000001]
+        (-1370912.72, -909968.64000000001, 1029087.28, 1490031.3600000001)
     )
 
 
 @pytest.fixture(scope="session")
 def area_def_lonlat_pm180_target():
     """Create an AreaDefinition with a geographic lon/lat projection with prime meridian at 180 (800, 850)."""
     return AreaDefinition(
-        'lonlat_pm180', '', '',
         {
             'proj': 'longlat',
             'pm': '180.0',
             'datum': 'WGS84',
             'no_defs': None,
         },
         DST_AREA_SHAPE[1], DST_AREA_SHAPE[0],
-        [-20.0, 20.0, 20.0, 35.0]
+        (-20.0, 20.0, 20.0, 35.0)
     )