Rename read_geotiff/write_geotiff to open_geotiff/to_geotiff (#1045)

Aligns with the base branch rename (PR #1056) to match xarray
conventions (open_* for readers, to_* for writers).

Updated in:
- xrspatial/geotiff/__init__.py (function defs, __all__)
- xrspatial/reproject/_datum_grids.py, _vertical.py (grid loading)
- README.md (all code examples and feature matrix)
- benchmarks/reproject_benchmark.md
- All geotiff test files (test_cog.py, test_edge_cases.py,
  test_features.py, bench_vs_rioxarray.py)

All 343 tests pass (271 geotiff + 72 reproject).

Author: brendancol

README.md

@@ -141,23 +141,23 @@ Native GeoTIFF and Cloud Optimized GeoTIFF reader/writer. No GDAL required.
 
 | Name | Description | NumPy | Dask | CuPy GPU | Dask+CuPy GPU | Cloud |
 |:-----|:------------|:-----:|:----:|:--------:|:-------------:|:-----:|
-| [read_geotiff](xrspatial/geotiff/__init__.py) | Read GeoTIFF / COG / VRT | ✅️ | ✅️ | ✅️ | ✅️ | ✅️ |
-| [write_geotiff](xrspatial/geotiff/__init__.py) | Write DataArray as GeoTIFF / COG | ✅️ | ✅️ | ✅️ | ✅️ | ✅️ |
+| [open_geotiff](xrspatial/geotiff/__init__.py) | Read GeoTIFF / COG / VRT | ✅️ | ✅️ | ✅️ | ✅️ | ✅️ |
+| [to_geotiff](xrspatial/geotiff/__init__.py) | Write DataArray as GeoTIFF / COG | ✅️ | ✅️ | ✅️ | ✅️ | ✅️ |
 | [write_vrt](xrspatial/geotiff/__init__.py) | Generate VRT mosaic from GeoTIFFs | ✅️ | | | | |
 
-`read_geotiff` and `write_geotiff` auto-dispatch to the correct backend:
+`open_geotiff` and `to_geotiff` auto-dispatch to the correct backend:
 
 ```python
-read_geotiff('dem.tif')                              # NumPy
-read_geotiff('dem.tif', chunks=512)                  # Dask
-read_geotiff('dem.tif', gpu=True)                    # CuPy (nvCOMP + GDS)
-read_geotiff('dem.tif', gpu=True, chunks=512)        # Dask + CuPy
-read_geotiff('https://example.com/cog.tif')          # HTTP COG
-read_geotiff('s3://bucket/dem.tif')                  # Cloud (S3/GCS/Azure)
-read_geotiff('mosaic.vrt')                           # VRT mosaic (auto-detected)
-
-write_geotiff(cupy_array, 'out.tif')                 # auto-detects GPU
-write_geotiff(data, 'out.tif', gpu=True)             # force GPU compress
+open_geotiff('dem.tif')                              # NumPy
+open_geotiff('dem.tif', chunks=512)                  # Dask
+open_geotiff('dem.tif', gpu=True)                    # CuPy (nvCOMP + GDS)
+open_geotiff('dem.tif', gpu=True, chunks=512)        # Dask + CuPy
+open_geotiff('https://example.com/cog.tif')          # HTTP COG
+open_geotiff('s3://bucket/dem.tif')                  # Cloud (S3/GCS/Azure)
+open_geotiff('mosaic.vrt')                           # VRT mosaic (auto-detected)
+
+to_geotiff(cupy_array, 'out.tif')                 # auto-detects GPU
+to_geotiff(data, 'out.tif', gpu=True)             # force GPU compress
 write_vrt('mosaic.vrt', ['tile1.tif', 'tile2.tif'])  # generate VRT
 ```
 
@@ -517,10 +517,10 @@ Importing `xrspatial` registers an `.xrs` accessor on DataArrays and Datasets, g
 
 ```python
 import xrspatial as xrs
-from xrspatial.geotiff import read_geotiff, write_geotiff
+from xrspatial.geotiff import open_geotiff, to_geotiff
 
 # Read a GeoTIFF (no GDAL required)
-elevation = read_geotiff('dem.tif')
+elevation = open_geotiff('dem.tif')
 
 # Surface analysis
 slope = elevation.xrs.slope()
@@ -529,7 +529,7 @@ aspect = elevation.xrs.aspect()
 
 # Reproject and write as a Cloud Optimized GeoTIFF
 dem_wgs84 = elevation.xrs.reproject(target_crs='EPSG:4326')
-write_geotiff(dem_wgs84, 'output.tif', cog=True)
+to_geotiff(dem_wgs84, 'output.tif', cog=True)
 
 # Classification
 classes = elevation.xrs.equal_interval(k=5)

benchmarks/reproject_benchmark.md

@@ -13,12 +13,12 @@ Python 3.14, NumPy, Numba, CuPy, Dask, pyproj, rioxarray (GDAL)
 Source file: Copernicus DEM COG (`Copernicus_DSM_COG_10_N40_00_W075_00_DEM.tif`), 3600x3600, WGS84, deflate+floating-point predictor. Reprojected to Web Mercator (EPSG:3857). Median of 3 runs after warmup.
 
 ```python
-from xrspatial.geotiff import read_geotiff, write_geotiff
+from xrspatial.geotiff import open_geotiff, to_geotiff
 from xrspatial.reproject import reproject
 
-dem = read_geotiff('Copernicus_DSM_COG_10_N40_00_W075_00_DEM.tif')
+dem = open_geotiff('Copernicus_DSM_COG_10_N40_00_W075_00_DEM.tif')
 dem_merc = reproject(dem, 'EPSG:3857')
-write_geotiff(dem_merc, 'output.tif')
+to_geotiff(dem_merc, 'output.tif')
 ```
 
 All times measured with warm Numba/CUDA kernels (first call incurs ~4.5s JIT compilation).

xrspatial/geotiff/__init__.py

@@ -4,9 +4,9 @@
 
 Public API
 ----------
-read_geotiff(source, ...)
+open_geotiff(source, ...)
     Read a GeoTIFF file to an xarray.DataArray.
-write_geotiff(data, path, ...)
+to_geotiff(data, path, ...)
     Write an xarray.DataArray as a GeoTIFF or COG.
 open_cog(url, ...)
     Read a Cloud Optimized GeoTIFF from an HTTP URL.
@@ -20,7 +20,7 @@
 from ._reader import read_to_array
 from ._writer import write
 
-__all__ = ['read_geotiff', 'write_geotiff', 'write_vrt']
+__all__ = ['open_geotiff', 'to_geotiff', 'write_vrt']
 
 
 def _wkt_to_epsg(wkt_or_proj: str) -> int | None:
@@ -98,7 +98,7 @@ def _coords_to_transform(da: xr.DataArray) -> GeoTransform | None:
     )
 
 
-def read_geotiff(source: str, *, window=None,
+def open_geotiff(source: str, *, window=None,
                  overview_level: int | None = None,
                  band: int | None = None,
                  name: str | None = None,
@@ -285,7 +285,7 @@ def _is_gpu_data(data) -> bool:
     return isinstance(data, _cupy_type)
 
 
-def write_geotiff(data: xr.DataArray | np.ndarray, path: str, *,
+def to_geotiff(data: xr.DataArray | np.ndarray, path: str, *,
                   crs: int | str | None = None,
                   nodata=None,
                   compression: str = 'zstd',
@@ -449,7 +449,7 @@ def write_geotiff(data: xr.DataArray | np.ndarray, path: str, *,
 def open_cog(url: str, **kwargs) -> xr.DataArray:
     """Deprecated: use ``read_geotiff(url, ...)`` instead.
 
-    read_geotiff handles HTTP URLs, cloud URIs, and local files.
+    open_geotiff handles HTTP URLs, cloud URIs, and local files.
     """
     return read_geotiff(url, **kwargs)
 

xrspatial/geotiff/tests/bench_vs_rioxarray.py

@@ -36,12 +36,12 @@ def _fmt_ms(seconds):
 def check_consistency(path):
     """Compare pixel values and geo metadata between the two readers."""
     import rioxarray  # noqa: F401
-    from xrspatial.geotiff import read_geotiff
+    from xrspatial.geotiff import open_geotiff
 
     rio_da = xr.open_dataarray(path, engine='rasterio')
     rio_arr = rio_da.squeeze('band').values.astype(np.float64)
 
-    our_da = read_geotiff(path)
+    our_da = open_geotiff(path)
     our_arr = our_da.values.astype(np.float64)
 
     # Shape
@@ -96,7 +96,7 @@ def check_consistency(path):
 def bench_read(path, runs=10):
     """Benchmark read performance."""
     import rioxarray  # noqa: F401
-    from xrspatial.geotiff import read_geotiff
+    from xrspatial.geotiff import open_geotiff
 
     def rio_read():
         da = xr.open_dataarray(path, engine='rasterio')
@@ -105,7 +105,7 @@ def rio_read():
         return da
 
     def our_read():
-        return read_geotiff(path)
+        return open_geotiff(path)
 
     rio_time, _ = _timer(rio_read, warmup=2, runs=runs)
     our_time, _ = _timer(our_read, warmup=2, runs=runs)
@@ -120,7 +120,7 @@ def our_read():
 def bench_write(shape=(512, 512), compression='deflate', runs=5):
     """Benchmark write performance."""
     import rioxarray  # noqa: F401
-    from xrspatial.geotiff import write_geotiff
+    from xrspatial.geotiff import to_geotiff
     from xrspatial.geotiff._geotags import GeoTransform
 
     rng = np.random.RandomState(42)
@@ -150,7 +150,7 @@ def rio_write():
 
     def our_write():
         p = os.path.join(tmpdir, 'our_out.tif')
-        write_geotiff(da_ours, p, compression=compression, tiled=False)
+        to_geotiff(da_ours, p, compression=compression, tiled=False)
         return os.path.getsize(p)
 
     rio_time, rio_size = _timer(rio_write, warmup=1, runs=runs)
@@ -166,7 +166,7 @@ def our_write():
 def bench_round_trip(shape=(256, 256), compression='deflate'):
     """Write with our module, read back with rioxarray, and vice versa."""
     import rioxarray  # noqa: F401
-    from xrspatial.geotiff import read_geotiff, write_geotiff
+    from xrspatial.geotiff import open_geotiff, to_geotiff
 
     rng = np.random.RandomState(99)
     arr = rng.rand(*shape).astype(np.float32)
@@ -179,7 +179,7 @@ def bench_round_trip(shape=(256, 256), compression='deflate'):
     our_path = os.path.join(tmpdir, 'ours.tif')
     da_ours = xr.DataArray(arr, dims=['y', 'x'], coords={'y': y, 'x': x},
                            attrs={'crs': 4326})
-    write_geotiff(da_ours, our_path, compression=compression, tiled=False)
+    to_geotiff(da_ours, our_path, compression=compression, tiled=False)
 
     rio_da = xr.open_dataarray(our_path, engine='rasterio')
     rio_arr = rio_da.squeeze('band').values if 'band' in rio_da.dims else rio_da.values
@@ -198,7 +198,7 @@ def bench_round_trip(shape=(256, 256), compression='deflate'):
     else:
         da_rio.rio.to_raster(rio_path)
 
-    our_da = read_geotiff(rio_path)
+    our_da = open_geotiff(rio_path)
     our_arr = our_da.values
 
     diff2 = float(np.nanmax(np.abs(arr - our_arr)))

xrspatial/geotiff/tests/test_cog.py

@@ -5,7 +5,7 @@
 import pytest
 import xarray as xr
 
-from xrspatial.geotiff import read_geotiff, write_geotiff
+from xrspatial.geotiff import open_geotiff, to_geotiff
 from xrspatial.geotiff._header import parse_header, parse_all_ifds
 from xrspatial.geotiff._writer import write
 from xrspatial.geotiff._geotags import GeoTransform, extract_geo_info
@@ -83,9 +83,9 @@ def test_read_write_round_trip(self, tmp_path):
         )
 
         path = str(tmp_path / 'round_trip.tif')
-        write_geotiff(da, path, compression='deflate', tiled=False)
+        to_geotiff(da, path, compression='deflate', tiled=False)
 
-        result = read_geotiff(path)
+        result = open_geotiff(path)
         np.testing.assert_array_almost_equal(result.values, data, decimal=5)
         assert result.attrs.get('crs') == 4326
 
@@ -95,40 +95,40 @@ def test_read_geotiff_name(self, tmp_path):
         path = str(tmp_path / 'myfile.tif')
         write(arr, path, compression='none', tiled=False)
 
-        da = read_geotiff(path)
+        da = open_geotiff(path)
         assert da.name == 'myfile'
 
     def test_read_geotiff_custom_name(self, tmp_path):
         arr = np.zeros((4, 4), dtype=np.float32)
         path = str(tmp_path / 'test.tif')
         write(arr, path, compression='none', tiled=False)
 
-        da = read_geotiff(path, name='custom')
+        da = open_geotiff(path, name='custom')
         assert da.name == 'custom'
 
     def test_write_numpy_array(self, tmp_path):
         """write_geotiff should accept raw numpy arrays too."""
         arr = np.arange(16, dtype=np.float32).reshape(4, 4)
         path = str(tmp_path / 'numpy.tif')
-        write_geotiff(arr, path, compression='none')
+        to_geotiff(arr, path, compression='none')
 
-        result = read_geotiff(path)
+        result = open_geotiff(path)
         np.testing.assert_array_equal(result.values, arr)
 
     def test_write_3d_rgb(self, tmp_path):
         """3D arrays (height, width, bands) should write multi-band."""
         arr = np.zeros((4, 4, 3), dtype=np.uint8)
         arr[:, :, 0] = 255  # red channel
         path = str(tmp_path / 'rgb.tif')
-        write_geotiff(arr, path, compression='none')
+        to_geotiff(arr, path, compression='none')
 
-        result = read_geotiff(path)
+        result = open_geotiff(path)
         np.testing.assert_array_equal(result.values, arr)
 
     def test_write_rejects_4d(self, tmp_path):
         arr = np.zeros((2, 3, 4, 4), dtype=np.float32)
         with pytest.raises(ValueError, match="Expected 2D or 3D"):
-            write_geotiff(arr, str(tmp_path / 'bad.tif'))
+            to_geotiff(arr, str(tmp_path / 'bad.tif'))
 
 
 def read_to_array_local(path):