add: reader level option for XarrayReader (#863)

* add: reader level option for XarrayReader

* fix

Author: vincentsarago

CHANGES.md

@@ -1,6 +1,10 @@
 
 # Unreleased
 
+# 9.0.0a5 (2026-02-13)
+
+* add: reader's level options for XarrayReader
+
 # 9.0.0a4 (2026-02-11)
 
 * fix: type hint for ImageData/PointData methods

rio_tiler/io/xarray.py

@@ -5,7 +5,7 @@
 import math
 import os
 import warnings
-from typing import Any, cast
+from typing import Any, TypedDict, cast
 
 import attr
 import numpy
@@ -55,6 +55,12 @@
 MAX_ARRAY_SIZE = int(os.environ.get("RIO_TILER_MAX_ARRAY_SIZE", 1_000_000_000))  # 1Gb
 
 
+class Options(TypedDict, total=False):
+    """Reader Options."""
+
+    nodata: NoData | None
+
+
 @attr.s
 class XarrayReader(BaseReader):
     """Xarray Reader.
@@ -81,8 +87,14 @@ class XarrayReader(BaseReader):
 
     tms: TileMatrixSet = attr.ib(default=WEB_MERCATOR_TMS)
 
+    options: Options = attr.ib()
+
     _dims: list = attr.ib(init=False, factory=list)
 
+    @options.default
+    def _options_default(self):
+        return {}
+
     def __attrs_post_init__(self):
         """Set bounds and CRS."""
         assert xarray is not None, "xarray must be installed to use XarrayReader"
@@ -168,6 +180,10 @@ def info(self) -> Info:
         """Return xarray.DataArray info."""
         metadata = [band.attrs for d in self._dims for band in self.input[d]] or [{}]
 
+        nodata_type = "None"
+        if self.options.get("nodata", self.input.rio.nodata) is not None:
+            nodata_type = "Nodata"
+
         meta = {
             "bounds": self.bounds,
             "crs": CRS_to_uri(self.crs) or self.crs.to_wkt(),
@@ -177,7 +193,7 @@ def info(self) -> Info:
                 for ix, v in enumerate(self.band_descriptions, 1)
             ],
             "dtype": str(self.input.dtype),
-            "nodata_type": "Nodata" if self.input.rio.nodata is not None else "None",
+            "nodata_type": nodata_type,
             "name": self.input.name,
             "count": self.input.rio.count,
             "width": self.input.rio.width,
@@ -233,6 +249,8 @@ def statistics(
 
         if nodata is not None:
             da = da.rio.write_nodata(nodata)
+        elif (nodata := self.options.get("nodata")) is not None:
+            da = da.rio.write_nodata(nodata)
 
         data = da.to_masked_array()
         data.mask |= data.data == da.rio.nodata
@@ -353,6 +371,8 @@ def part(  # noqa: C901
 
         if nodata is not None:
             da = da.rio.write_nodata(nodata)
+        elif (nodata := self.options.get("nodata")) is not None:
+            da = da.rio.write_nodata(nodata)
 
         # Forward valid_min/valid_max to the ImageData object
         minv, maxv = da.attrs.get("valid_min"), da.attrs.get("valid_max")
@@ -507,6 +527,8 @@ def preview(  # noqa: C901
 
         if nodata is not None:
             da = da.rio.write_nodata(nodata)
+        elif (nodata := self.options.get("nodata")) is not None:
+            da = da.rio.write_nodata(nodata)
 
         if dst_crs and dst_crs != self.crs:
             src_width = da.rio.width
@@ -641,6 +663,8 @@ def point(
 
         if nodata is not None:
             da = da.rio.write_nodata(nodata)
+        elif (nodata := self.options.get("nodata")) is not None:
+            da = da.rio.write_nodata(nodata)
 
         y, x = rowcol(da.rio.transform(), da_lon, da_lat)
 

tests/test_io_stac.py

@@ -20,6 +20,7 @@
 from rio_tiler.errors import InvalidAssetName, MissingAssets, TileOutsideBounds
 from rio_tiler.io import BaseReader, Reader, STACReader, XarrayReader
 from rio_tiler.io.stac import DEFAULT_VALID_TYPE
+from rio_tiler.io.xarray import Options
 from rio_tiler.models import BandStatistics
 from rio_tiler.types import AssetInfo
 
@@ -885,8 +886,14 @@ class NetCDFReader(XarrayReader):
         ds: xarray.Dataset = attr.ib(init=False)
         input: xarray.DataArray = attr.ib(init=False)
 
+        options: Options = attr.ib()
+
         _dims: List = attr.ib(init=False, factory=list)
 
+        @options.default
+        def _options_default(self):
+            return {}
+
         def __attrs_post_init__(self):
             """Set bounds and CRS."""
             self.ds = xarray.open_dataset(self.src_path, decode_coords="all")

tests/test_io_xarray.py

@@ -1017,3 +1017,74 @@ def test_max_pixels():
         # Should not raise error when using a small area
         img = dst.tile(0, 0, 5)
         assert img.array.shape == (3, 256, 256)
+
+
+def test_xarray_reader_nodata_option():
+    """test XarrayReader."""
+    # Create a 360/180 dataset that covers the whole world
+    arr = numpy.arange(0.0, 360 * 180).reshape(1, 180, 360)
+    arr[:, 0:50, 0:50] = 0  # we set the top-left corner to 0
+
+    data = xarray.DataArray(
+        arr,
+        dims=("time", "y", "x"),
+        coords={
+            "x": numpy.arange(-179.5, 180.5, 1),
+            "y": numpy.arange(89.5, -90.5, -1),
+            "time": [datetime(2022, 1, 1)],
+        },
+    )
+
+    data.attrs.update({"valid_min": arr.min(), "valid_max": arr.max()})
+
+    data.rio.write_crs("epsg:4326", inplace=True)
+    assert data.rio.nodata is None
+    with pytest.warns(
+        UserWarning,
+        match="Adjusting dataset latitudes to avoid re-projection overflow",
+    ):
+        with XarrayReader(data, options={"nodata": 0}) as dst:
+            info = dst.info()
+            assert info.height == 180
+            assert info.width == 360
+            assert info.count == 1
+
+            img = dst.tile(0, 0, 1)
+            assert not img._mask.all()  # not all the mask value are set to 255
+            assert img.array.mask[0, 0, 0]  # the top left pixel should be masked
+            assert not img.array.mask[0, 100, 100]  # pixel 100,100 shouldn't be masked
+            assert dst.input.rio.nodata is None
+
+            img = dst.part((-160, -80, 160, 80))
+            assert not img._mask.all()  # not all the mask value are set to 255
+            assert img.array.mask[0, 0, 0]  # the top left pixel should be masked
+            assert not img.array.mask[0, 100, 100]  # pixel 100,100 shouldn't be masked
+
+            # overwrite the nodata value to 0
+            pt = dst.point(-179, 89)
+            assert pt.count == 1
+            assert not pt._mask[0]
+            assert dst.input.rio.nodata is None
+
+            feat = {
+                "type": "Feature",
+                "geometry": {
+                    "type": "Polygon",
+                    "coordinates": [
+                        [
+                            [-180.0, 0],
+                            [-180.0, 85.0511287798066],
+                            [0, 85.0511287798066],
+                            [0, 6.023673383202919e-13],
+                            [-180.0, 0],
+                        ]
+                    ],
+                },
+                "properties": {"title": "XYZ tile (0, 0, 1)"},
+            }
+
+            img = dst.feature(feat)
+            assert not img._mask.all()  # not all the mask value are set to 255
+            assert img.array.mask[0, 0, 0]  # the top left pixel should be masked
+            assert not img.array.mask[0, 50, 100]  # pixel 50,100 shouldn't be masked
+            assert dst.input.rio.nodata is None