expand xarray capabilities (#755)

* expand xarray capabilities * update changelog * update version * fix attrs encoding * refactor feature and update docs * handle 2D dataset and invalid bounds * update example with NetCDF * check if the Y bounds are inverted and flip the image on the Y axis (#756) * check if the Y bounds are inverted and flip the image on the Y axis * Update tests/test_io_xarray.py Co-authored-by: Henry Rodman <[email protected]> * Update tests/test_io_xarray.py Co-authored-by: Henry Rodman <[email protected]> --------- Co-authored-by: Henry Rodman <[email protected]> * update changelog --------- Co-authored-by: Henry Rodman <[email protected]>
cogeotiff · Oct 28, 2024 · d3a552e · d3a552e
1 parent abec151
commit d3a552e
Show file tree

Hide file tree

Showing 7 changed files with 1,585 additions and 85 deletions.
diff --git a/CHANGES.md b/CHANGES.md
@@ -1,3 +1,19 @@
+# 7.1.0 (TBD)
+
+* Add `preview()` and `statistics()` methods to XarrayReader (https://github.com/cogeotiff/rio-tiler/pull/755)
+
+* Add output size (`max_size` | `width`, `height`) options for XarrayReader's `preview()`, `part()` and `feature()` methods (https://github.com/cogeotiff/rio-tiler/pull/755)
+
+* Add half X/Y resolution on bounds before checking the geographic bounds in XarrayReader (https://github.com/cogeotiff/rio-tiler/pull/755)
+
+* Check if the Y bounds are inverted and flip the image on the Y axis in XarrayReader (https://github.com/cogeotiff/rio-tiler/pull/756)
+
+* Add support for 2D arrays in XarrayReader (https://github.com/cogeotiff/rio-tiler/pull/755)
+
+* Cast Xarray `attrs` values in XarrayReader's `info()` response to avoid JSON encoding issues (https://github.com/cogeotiff/rio-tiler/pull/755)
+
+* refactor XarrayReader's `feature()` method to use the `part` method (https://github.com/cogeotiff/rio-tiler/pull/755)
+
 # 7.0.1 (2024-10-22)
 
 * Add `CRS_to_urn` method and update internals for `CRS_to_uri` (author @AndrewAnnex, https://github.com/cogeotiff/rio-tiler/pull/752)

diff --git a/docs/src/examples/Using-rio-tiler-XarrayReader.ipynb b/docs/src/examples/Using-rio-tiler-XarrayReader.ipynb
diff --git a/docs/src/readers.md b/docs/src/readers.md
@@ -998,7 +998,7 @@ For ImageReader we are using a custom `LocalTileMatrixSet` constructed from the
 
 ## rio_tiler.io.xarray.XarrayReader
 
-The `Reader` is designed to work with xarray.DataReader with full geo-reference metadata (CRS) and variables (X,Y)
+The `Reader` is designed to work with `xarray.DataReader` with full geo-reference metadata (CRS) and variables (X,Y)
 
 The class is derived from the `rio_tiler.io.base.BaseReader` class.
 ```python
@@ -1025,6 +1025,7 @@ XarrayReader.__mro__
 - **transform**: dataset's Affine transform
 - **height**: dataset's height
 - **width**: dataset's width
+- **band_names**: list of dataArray dims
 
 ```python
 import numpy
@@ -1071,7 +1072,7 @@ EPSG:4326
     from rio_tiler.models import ImageData
 
     with XarrayReader(data) as src:
-        # src.tile(tile_x, tile_y, tile_z, tilesize, reproject_method)
+        # src.tile(tile_x, tile_y, tile_z, tilesize, reproject_method, auto_expand, nodata)
         img = src.tile(1, 2, 3)
         assert isinstance(img, ImageData)
         assert img.crs == WEB_MERCATOR_CRS
@@ -1084,7 +1085,7 @@ EPSG:4326
     from rio_tiler.models import ImageData
 
     with XarrayReader(data) as src:
-        # src.part((minx, miny, maxx, maxy), dst_crs, bounds_crs, reproject_method)
+        # src.part((minx, miny, maxx, maxy), dst_crs, bounds_crs, reproject_method, auto_expand, nodata, max_size, height, width, resampling_method)
         img = src.part((10, 10, 20, 20))
         assert isinstance(img, ImageData)
         assert img.crs == WGS84_CRS
@@ -1121,7 +1122,7 @@ EPSG:4326
     }
 
     with XarrayReader(data) as src:
-        # src.part(geojson_feature, **kwargs)
+        # src.part(geojson_feature, dst_crs, shape_crs, auto_expand, nodata, max_size, height, width, resampling_method)
         img = src.feature(feat)
         assert isinstance(img, ImageData)
         assert img.crs == WGS84_CRS
@@ -1173,16 +1174,68 @@ EPSG:4326
     }
     ```
 
-- **preview()**:
+- **preview()**: Return low-resolution representation of the DataArray
 
-!!! Important
+    ```python
+    from rio_tiler.io import XarrayReader
+    from rio_tiler.models import ImageData
 
-    Not Implemented
+    with XarrayReader(data) as src:
+        # src.preview(dst_crs, reproject_method, nodata, max_size, height, width, resampling_method)
+        img = src.preview()
+        assert isinstance(img, ImageData)
+        assert img.crs == data.rio.crs
+        assert img.bounds == data.rio.bounds()
+
+    with XarrayReader(data) as src:
+        img = src.preview(WGS84_CRS, max_size=100)
+        assert img.crs == WGS84_CRS
+    ```
 
+    !!! warnings
 
-- **statistics()**:
+        This method will read the whole DataArray into memory
 
-!!! Important
+- **statistics()**: Return DataArray statistics (Min/Max/Stdev)
+
+    ```python
+    from rio_tiler.io import XarrayReader
+    from rio_tiler.models import ImageData
+
+    with XarrayReader(data) as src:
+        stats = src.statistics()
+        assert isinstance(stats, dict)
+
+    # stats will be in form or {"band": BandStatistics(), ...}
+    print(stats)
+    >>> {
+        '2022-01-01T00:00:00.000000000': BandStatistics(...),
+    }
+
+    print(stats["2022-01-01T00:00:00.000000000"].model_dump())
+    >>> {
+        "min": 1,
+        "max": 7872,
+        "mean": 2107.524612053134,
+        "count": 1045504,
+        "sum": 2203425412,
+        "std": 2271.0065537857326,
+        "median": 2800,
+        "majority": 1,
+        "minority": 7072,
+        "unique": 15,
+        "histogram": [
+            [...],
+            [...]
+        ],
+        "valid_percent": 100,
+        "masked_pixels": 0,
+        "valid_pixels": 1045504,
+        "percentile_98": 6896,
+        "percentile_2": 1
+    }
+    ```
 
-    Not Implemented
+    !!! warnings
 
+        This method will read the whole DataArray into memory
diff --git a/pyproject.toml b/pyproject.toml
@@ -157,7 +157,7 @@ ignore = [
 max-complexity = 14
 
 [tool.bumpversion]
-current_version = "7.0.1"
+current_version = "7.1.0"
 search = "{current_version}"
 replace = "{new_version}"
 regex = false

diff --git a/rio_tiler/__init__.py b/rio_tiler/__init__.py
@@ -1,6 +1,6 @@
 """rio-tiler."""
 
-__version__ = "7.0.1"
+__version__ = "7.1.0"
 
 from . import (  # noqa
     colormap,