Pyresample 2.0 AreaDefinition interface changes

[djhoese]

While working on #464 it was realized that there isn't a Pyresample 2.0 issue specifically for how/where AreaDefinition's should change. I think this is primarily missing because we didn't have great ideas for how much we wanted to break backwards compatibility. This is a discussion topic meant to be a place for brainstorming ideas and getting feedback. I don't use GitHub Discussions very much, but I was thinking we could try to do main comments for ideas and then sub-comments for feedback of those ideas. I'll try to copy feedback from #464 and other places.

Note: #464 already includes removing area_id, proj_id, and description as required arguments in favor of a attrs metadata dictionary.

[djhoese]

Replace width and height with shape. This follows the "Clean Code" idea of pairing like-arguments together in a single structure. It also allows us the flexibility (in multiple interfaces/functions) to specify geometries with more than 2 dimensions.

[mraspaud]

I agree with this.

[djhoese]

From @ghiggi:

For AreaDefinition, many methods are not clear if they return data in xy or lat/lon; the pixel centroid or the outermost pixel corner. Maybe would be worth adding a common suffix (i.e. _ll) when they return lat/lons, and otherwise expect they return xy coords. This will enhance code readability.
Example:

• area_def.corners currently returns the centroid lat/lon coords in the very old spherical object
• area_def.outer_boundary_corners currently returns the corners lat/lon coords in the very old spherical object
  --> Possible new methods: corners_centroids, corners, corners_centroids_ll, corners_ll ... or see next bullet point

[ghiggi]

Maybe suffix _lonlat to preferred instead of _ll

[djhoese]

From @ghiggi:

Add utility properties like upper_left_corner_ll, upper_left_centroid_ll,
A possible pattern: <lower/upper>_<right/left>_<''/'ll'> (or bottom instead of lower).
Currently the upper_left_corner is provided by upper_left_extent

[mraspaud]

related to the genericity of shape vs width and height, should we have a more general property, like corner_centroids or something? (ie not specifying dimensions)

[djhoese]

Regarding "corner", I think we should still with consistent terminology and for historical reasons I think "extent" should be used. If there is a strong argument that "corner" is much clearer than "extent" then we can have that discussion. I'd say that an extent is not necessarily the "corner" of a swath-like dataset (lower-left corner is the lower-left pixel, but the lower-left extent is the intersection of the left-most bound and the bottom-most bound)

If we're doing a lower/upper thing then the alternative should be bottom/top (not bottom/upper). I'm not sure I care for one over the other. I think in english saying "upper left extent" sounds better than "top left extent", but I'm not sure that opinion is shared.

should we have a more general property, like corner_centroids or something

Hm interesting...should we maybe have a .extents that is a namedtuple or dataclass or something similar that has convenience properties for .extents.lower_left that returns (left x, lower y) and may itself be a special class that has a .x and a .y property? Based on your comment Martin I guess that makes the centroid version .corner_centroids.lower_left?

[djhoese]

From @ghiggi:

Add xy_bbox and ll_bbox properties for consistency with satpy? Equivalent to area_extent and area_extent_ll

[djhoese]

In the new version of the class I'd like to remove "convenience" or replicated properties as much as possible. If we want to come up with a new standard name fine, but let's try to stick with one. Similarly, if ll is the abbreviation then it should be used everywhere and not lonlat...but lonlat tells you the order of the coordinate axes (longitude then latitude) so maybe that should be preferred.

[djhoese]

I'd also vote for area_extent being renamed to just extent. We know it is an area already, this is just the extent of it. Or extents? Similar to .bounds, .corners, and/or bounding_polygon perhaps.

[djhoese]

From @ghiggi:

Current area_extent_<> and <>_bbox follow the (xmin, ymin, xmax, ymax) convention. More precisely the area_extent is defined as (lower_left_x, lower_left_y, upper_right_x, upper_right_y).

• This is also the convention adopted by rasterio/rioxarray/shapely object bounds method.
  --> Maybe we could add a bounds property?
• When retrieving the area_extent_ll (in lat/lon) the lower-left and upper-right corners do not necessarily currently define the outermost lat/lon coordinates of the area. Maybe this method should be changed! And maybe we could also add a bounds_ll method.
• Additionally, the area_extent convention differs from the i.e. matplotlib cartopy and matplotlib extent which is defined as (xmin, xmax, ymin, ymax)
  --> Maybe we could add a <mpl/cartopy>_area_extent_<''/ll> property?

[djhoese]

From @ghiggi:

For GEO AreaDef, all the above _ll methods currently return np.nan/np.inf values. Maybe ad-hoc processing using get_geostationary_bounding_box_in_lonlats could be implemented for area_extent_ll, but the corners would remain undefined ! Maybe would be worth raising an error to avoid downstream bugs !

[djhoese]

Deprecate/remove nprocs and likely dtype. Both of these should be specified per-call to functions that return new arrays and should default to whatever the internal data structures work. Likely defaulting to 64-bit floats.

[ghiggi]

An additional note to area_extent in lon/lat @djhoese:

For SwathDefinition or AreaDefinition crossing the antimeridian (like for GOES-17 Full Disc), the definition of area_extent_ll in lon_lat is ambiguous.
Currently, SwathDefinition does not have an extent/area_extent attribute.
Currently, for AreaDefinition the area_extent_ll xmin and xmax are defined by projecting to lat/lon the area_extent[0], area_extent[2]. For antimeridian crossing AreaDefinition, it means that the area_extent_ll has xmin>xmax

In the future.spherical, I started implementing an SExtent object which can be defined by a list of area_extent. The SExtent object enables then to check for i.e. intersection with other SExtent objects.
In the case of antimeridian crossing Swath/Area, we can provide two extents: one going to xmax=180 and another one starting from xmin=-180. As an example for GOES-17 FD, the SExtent would be defined by list_extent = [[150, 180, -70, 70], [-180,-150, -70, 70]]

Maybe an option could be to return the SExtent object from area_extent_ll.

[djhoese]

What about no BaseDefinition class? Besides isinstance checks which should probably use duck typing instead, do we need it? I think we could just design things by "composition". That is, build up the functionality in separate and specific helper classes.