Rename GeoTIFF API to xarray conventions: open_geotiff / to_geotiff

[brendancol]

Author of Proposal: @brendan

Reason or problem

The GeoTIFF API uses read_geotiff / write_geotiff, which doesn't follow xarray's naming conventions. xarray uses open_* for readers (xr.open_dataset, xr.open_zarr) and to_* for writers (ds.to_netcdf(), ds.to_zarr()). Users familiar with xarray expect this pattern.

There's also no way to call these from the .xrs accessor. You can't write da.xrs.to_geotiff('out.tif') the way you'd write da.to_netcdf('out.nc'). And there's no accessor-based reader that uses an existing Dataset's spatial extent as a read window -- useful when you want to load a GeoTIFF cropped to match data already in memory.

Proposal

Design:

1. Rename the primary functions:
   • read_geotiff becomes open_geotiff (matches xr.open_dataset)
   • write_geotiff becomes to_geotiff (matches ds.to_netcdf)
2. Keep read_geotiff and write_geotiff as deprecated aliases that forward to the new names, so existing code doesn't break.
3. Add accessor methods to both XrsSpatialDataArrayAccessor and XrsSpatialDatasetAccessor:
   • da.xrs.to_geotiff(path, **kwargs) -- writes the DataArray/Dataset as a GeoTIFF
   • ds.xrs.open_geotiff(path, **kwargs) -- reads a GeoTIFF windowed to the Dataset's spatial extent. Computes the pixel window from the Dataset's y/x coordinates and the file's GeoTransform, then calls open_geotiff(path, window=...).

Usage:

from xrspatial.geotiff import open_geotiff, to_geotiff

# Standalone (same as before, new names)
da = open_geotiff('dem.tif')
to_geotiff(da, 'out.tif', crs=4326)

# Accessor -- write
da.xrs.to_geotiff('out.tif', compression='lzw')

# Accessor -- read windowed to existing extent
ds = xr.Dataset(...)  # has y/x coordinates covering some area
cropped = ds.xrs.open_geotiff('large_dem.tif')

Aligning with xarray conventions makes the API easier to find for users who already know xarray. The accessor read gives you spatial windowing without manual coordinate math.

Stakeholders and impacts

Existing read_geotiff / write_geotiff imports keep working through deprecated aliases. The __all__ export list and README need updating. Tests need to cover both old and new names.

Drawbacks

Adds two deprecated aliases that stick around until a major version bump.

Alternatives

• Keep read_geotiff / write_geotiff as primary names and only add the accessor. Doesn't fix the naming inconsistency.
• Add open_geotiff / to_geotiff as equal aliases without deprecating the old names. Two names for the same function is confusing.

Unresolved questions

None.

Additional notes

open_cog is already deprecated in favor of read_geotiff. This continues that direction.