add experimental features (#786)

Author: vincentsarago

CHANGES.md

@@ -1,4 +1,9 @@
 
+# 7.5.0 (2025-02-26)
+
+* add `rio_tiler.experimental` submodule
+* add `rio_tiler.experimental.vsifile.VSIReader` VSIFile based experimental reader
+
 # 7.4.0 (2025-01-28)
 
 * update rasterio dependency to `>=1.4.0`

docs/mkdocs.yml

@@ -31,6 +31,7 @@ nav:
     - Mosaic: 'mosaic.md'
     - Colormaps: 'colormap.md'
     - Supported file formats: 'supported_format.md'
+    - Experimental: experimental.md
   - Advanced Topics:
     - Base classes and custom readers: 'advanced/custom_readers.md'
     - Read Polygon-shaped regions: 'advanced/feature.md'

docs/src/experimental.md

@@ -0,0 +1,44 @@
+# Experimental Features
+
+In this section you will find documentation for new, experimental features in rio-tiler. These features are subject to change or removal, and we are looking for feedback and suggestions before making them a permanent part of Pydantic.
+
+
+## Feedback
+
+We welcome feedback on experimental features! Please open an issue on the [rio-tiler GitHub repository](https://github.com/cogeotiff/rio-tiler/issues/new/choose) to share your thoughts, requests, or suggestions.
+
+We also encourage you to read through existing feedback and add your thoughts to existing issues.
+
+## Warnings on Import
+
+When you import an experimental feature from the `experimental` module, you'll see a warning message that the feature is experimental. You can disable this warning with the following:
+
+```python
+import warnings
+from rio_tiler.errors import RioTilerExperimentalWarning
+
+warnings.filterwarnings('ignore', category=RioTilerExperimentalWarning)
+```
+
+## VSIFile Reader
+
+Required dependencies:
+- `vsifile>=0.2`
+
+A rio-tiler Reader using VSIFile/Obstore as file system handler. Starting with GDAL>=3.0, **VSI plugin** was added in order to enable users to provide their own file system handler (class handling the file requests).
+
+The reader is considered experimental because [`VSIFile`](https://github.com/vincentsarago/vsifile) is still under development. Users should also note that changes available in GDAL>=3.10 will drastically improve the performance of this reader (https://github.com/vincentsarago/vsifile/issues/13#issuecomment-2683310594)
+
+```python
+from rio_tiler.experimental.vsifile import VSIReader
+
+with VSIReader("https://sentinel-cogs.s3.us-west-2.amazonaws.com/sentinel-s2-l2a-cogs/15/T/VK/2023/10/S2B_15TVK_20231008_0_L2A/TCI.tif") as src:
+    print(src.info())
+
+>>> bounds=(399960.0, 4890240.0, 509760.0, 5000040.0) crs='http://www.opengis.net/def/crs/EPSG/0/32615' band_metadata=[('b1', {}), ('b2', {}), ('b3', {})] band_descriptions=[('b1', ''), ('b2', ''), ('b3', '')] dtype='uint8' nodata_type='Nodata' colorinterp=['red', 'green', 'blue'] scales=[1.0, 1.0, 1.0] offsets=[0.0, 0.0, 0.0] colormap=None driver='GTiff' count=3 width=10980 height=10980 overviews=[2, 4, 8, 16] nodata_value=0.0
+```
+
+#### Links
+
+- https://github.com/OSGeo/gdal/pull/1289
+- https://github.com/rasterio/rasterio/pull/2141

pyproject.toml

@@ -38,7 +38,6 @@ dependencies = [
 test = [
     "pytest",
     "pytest-cov",
-
     # XarrayReader
     "xarray",
     "rioxarray",
@@ -47,6 +46,8 @@ test = [
     "boto3",
     # Some tests will fail with 5.0
     "morecantile>=6.0,<7.0",
+    # Experimental
+    "vsifile>=0.2",
 ]
 
 benchmark = [

rio_tiler/errors.py

@@ -91,3 +91,7 @@ class MissingCRS(RioTilerError):
 
 class InvalidGeographicBounds(RioTilerError):
     """Invalid Geographic bounds."""
+
+
+class RioTilerExperimentalWarning(UserWarning):
+    """A rio-tiler specific experimental functionality warning."""

rio_tiler/experimental/__init__.py

@@ -0,0 +1,10 @@
+"""The "experimental" module of rio-tiler contains potential new features that are subject to change."""
+
+import warnings
+
+from rio_tiler.errors import RioTilerExperimentalWarning
+
+warnings.warn(
+    "This module is experimental, its contents are subject to change and deprecation.",
+    category=RioTilerExperimentalWarning,
+)

rio_tiler/experimental/vsifile.py

@@ -0,0 +1,36 @@
+"""rio_tiler.io.Reader with VSIFILE/Obstore Opener."""
+
+from typing import Union
+
+import attr
+import rasterio
+from rasterio.io import DatasetReader, DatasetWriter, MemoryFile
+from rasterio.vrt import WarpedVRT
+
+from rio_tiler.io import Reader
+
+try:
+    import vsifile
+    from vsifile.rasterio import opener
+except ImportError:  # pragma: nocover
+    vsifile = None  # type: ignore
+    opener = None  # type: ignore
+
+
+@attr.s
+class VSIReader(Reader):
+    """Rasterio Reader with VSIFILE opener."""
+
+    dataset: Union[DatasetReader, DatasetWriter, MemoryFile, WarpedVRT] = attr.ib(
+        default=None, init=False
+    )
+
+    def __attrs_post_init__(self):
+        """Use vsifile.rasterio.opener as Python file opener."""
+        assert vsifile is not None, "VSIFILE must be installed to use VSIReader"
+
+        self.dataset = self._ctx_stack.enter_context(
+            rasterio.open(self.input, opener=opener)
+        )
+
+        super().__attrs_post_init__()

tests/test_io_vsifile.py

@@ -0,0 +1,34 @@
+"""test VSIReader."""
+
+import os
+
+import numpy
+import pytest
+
+from rio_tiler.errors import RioTilerExperimentalWarning
+from rio_tiler.io import Reader
+
+PREFIX = os.path.join(os.path.dirname(__file__), "fixtures")
+COGEO = os.path.join(PREFIX, "cog.tif")
+
+
+def test_vsireader():
+    """Test Reader using VSIFile handler."""
+    pytest.importorskip("vsifile")
+
+    with pytest.warns((RioTilerExperimentalWarning)):
+        from rio_tiler.experimental.vsifile import VSIReader
+
+    # VSIReader doesn't take dataset as input
+    with pytest.raises(TypeError):
+        with VSIReader(COGEO, dataset="cog"):
+            pass
+
+    with VSIReader(COGEO) as vsi, Reader(COGEO) as src:
+        assert vsi.bounds == src.bounds
+        assert vsi.crs == src.crs
+        assert vsi.info().model_dump() == src.info().model_dump()
+
+        img_vsi = vsi.preview()
+        img_src = src.preview()
+        assert numpy.array_equal(img_vsi.array, img_src.array)