Simplify the spatial information (projection and extent) is provided to Xee

[tylere]

Background

The core of Xee is providing an entrypoint so that Xarray can open datasets hosted on (or computed by) Earth Engine. The main user-facing method for accomplishing this is the open_dataset method, which has several parameters for describing the spatial characteristics of the data to be retrieved from Earth Engine.

  crs (optional): The coordinate reference system (a CRS code or WKT
    string). This defines the frame of reference to coalesce all variables
    upon opening. By default, data is opened with `EPSG:4326'.
  scale (optional): The scale in the `crs` or `projection`'s units of
    measure -- either meters or degrees. This defines the scale that all
    data is represented in upon opening. By default, the scale is 1° when
    the CRS is in degrees or 10,000 when in meters.
  projection (optional): Specify an `ee.Projection` object to define the
    `scale` and `crs` (or other coordinate reference system) with which to
    coalesce all variables upon opening. By default, the scale and reference
    system is set by the the `crs` and `scale` arguments.
  geometry (optional): Specify an `ee.Geometry` to define the regional
    bounds when opening the data or a bbox specifying [x_min, y_min, x_max,
    y_max] in EPSG:4326. When not set, the bounds are defined by
    the CRS's 'area_of_use` boundaries. If those aren't present, the bounds
    are derived from the geometry of the first image of the collection.

These parameters are all optional and may provide conflicting information, and the intended behavior when conflicting information is provided is not clearly described. This behavior and documentation have resulted in numerous Xee issues related to projection information, both open (examples: #215, #208, #207, #198, #171, #158) and closed (examples: #193, #192, #176, #173, #139, #118, #96).

What information does Xee need to provide to Earth Engine?

Xee accesses GEE using a projects.image.computePixels call, passing a PixelGrid object to describe how the image should be reprojected and clipped. The PixelGrid is defined with three parameters:

1. crs: as either a "crsCode" or "crsWkt" string which defines the projection
2. affineTransform: AffineTransform {"scaleX": number, "shearX": number, "translateX": number, "shearY": number, "scaleY": number, "translateY": number} which defines the offset from the projection origin and the pixel size.
   • Related references: GDAL Affine GeoTransform, rasterio/affine
3. dimensions: {"width": integer, "height": integer} which define the size of the raster image that GEE returns.

This abstraction model matches up with the abstractions used by other open source Python libraries that work with Xarray including:

• OpenDataCube's GeoBox model (docs, GitHub) which has parameters (crs, affine, shape)
• rioxarray's raster_array.RasterArray.reproject which has parameters (dst_crs, transform, shape)

Proposed changes to Xee

My proposal is to:

1. rewrite Xee's open_dataset() method and EarthEngineStore class to require the three parameters needed by Earth Engine: crs, affine_transform, and shape. This will simplify the logic of Xee.

2. Add helper functions that can be used to calculate the three core parameters. Requiring users to explicitly call these helper functions should code clearer to understand and debug.
   Here are some helper functions that could be useful:

   1. Given a geometry, crs, and transform, return the 3 parameters with the affine_transform's translateX and translateY parameters updated to match the geometry.
   2. Given a geometry, crs, and dimensions, return the 3 parameters with the affine_transform's scaleX and scaleY parameters updated to match the geometry.
   3. Given an ee.ImageCollection object, return a crs string and affine_transform matrix based on the first image in the image collection.
   4. Given a ee.Projection and geometry, return the 3 parameters.

These changes would potentially be breaking for some users. But given Xee's handling of projections other than crs='EPSG:4326' is largely broken (#207), there should be limited impact on users. If implemented, these changes should result in a new MINOR version number.

[alxmrs]

Thanks Tyler! I'm happy with this breaking change as well. I'm especially persuaded when you compare Xee's parameters to the standards established by other libraries.

[jdbcode]

This is great, Tyler, thanks! I'm in support of it and understand that it could break some uses.

[DecaiJin]

I believe the iv helper functions is good. The mixed of crs and projection is confusing and it had appeared the bug#207. Try to avoid using pyproj. @tylere

[tylere]

@DecaiJin a PR for this is under review: #225
Removing pyproj is out of scope, but I filed an issue here: #229