Merge branch 'main' into kyle/as-masked

Author: kylebarron

DEVELOP.md

@@ -11,3 +11,7 @@ Build locally:
 ```
 uv run --group docs mkdocs serve
 ```
+
+## References
+
+- aiocogeo: https://github.com/geospatial-jeff/aiocogeo

README.md

@@ -1,20 +1,95 @@
 # async-geotiff
 
-Async GeoTIFF and [Cloud-Optimized GeoTIFF][cogeo] (COG) reader for Python, wrapping [`async-tiff`][async-tiff].
+Fast, async GeoTIFF and [Cloud-Optimized GeoTIFF][cogeo] (COG) reader for Python, wrapping the Rust-based [Async-TIFF][async-tiff] library.
 
 [async-tiff]: https://github.com/developmentseed/async-tiff
 [cogeo]: https://cogeo.org/
 
-## Project Goals:
+## Features
 
-- Support only for GeoTIFF and Cloud-Optimized GeoTIFF (COG) formats
-- Support for reading only, no writing support
-- Full type hinting.
-- API similar to rasterio where possible.
-    - We won't support the full rasterio API, but we'll try to when it's possible to implement rasterio APIs with straightforward maintenance requirements.
-    - For methods where we do intentionally try to match with rasterio, the tests should match against rasterio.
-- Initially, we'll try to support a core set of GeoTIFF formats. Obscure GeoTIFF files may not be supported.
+- Read-only support for GeoTIFF and COG formats.
+- High-level, familiar, easy to use API.
+- Performance-focused:
+    - Rust core ensures native performance.
+    - CPU-bound tasks like image decoding happen in a thread pool, without blocking the async executor.
+    - Buffer protocol integration for zero-copy data sharing between Rust and Python.
+- Lightweight with no GDAL dependency.
+- Integration with [obstore] for efficient data access on object stores.
+- Full type hinting for all operations.
+- Broad decompression support: Deflate, LZW, JPEG, JPEG2000, WebP, ZSTD.
 
-## References
+**Anti-Features** (features explicitly not in scope):
 
-- aiocogeo: https://github.com/geospatial-jeff/aiocogeo
+- No pixel resampling.
+- No warping/reprojection.
+
+Resampling and warping bring significant additional complexity and are out of scope for this library.
+
+[obstore]: https://developmentseed.org/obstore/latest/
+[obspec]: https://developmentseed.org/obspec/latest/
+
+## Example
+
+First create a "store", such as an [`S3Store`][S3Store], [`GCSStore`][GCSStore], [`AzureStore`][AzureStore], or [`LocalStore`][LocalStore] for reading data from AWS S3, Google Cloud, Azure Storage, or local files. Refer to [obstore] documentation for more information.
+
+[S3Store]: https://developmentseed.org/obstore/latest/api/store/aws/#obstore.store.S3Store
+[GCSStore]: https://developmentseed.org/obstore/latest/api/store/gcs/#obstore.store.GCSStore
+[AzureStore]: https://developmentseed.org/obstore/latest/api/store/azure/#obstore.store.AzureStore
+[LocalStore]: https://developmentseed.org/obstore/latest/api/store/local/#obstore.store.LocalStore
+
+```py
+from obstore.store import S3Store
+
+store = S3Store("sentinel-cogs", region="us-west-2", skip_signature=True)
+path = "sentinel-s2-l2a-cogs/12/S/UF/2022/6/S2B_12SUF_20220609_0_L2A/TCI.tif"
+```
+
+Then open a `GeoTIFF`:
+
+```py
+from async_geotiff import GeoTIFF
+
+geotiff = await GeoTIFF.open(path, store=store)
+```
+
+On the `GeoTIFF` instance you have metadata about the image, such as its affine transform and Coordinate Reference System:
+
+```py
+geotiff.transform
+# Affine(10.0, 0.0, 300000.0,
+#        0.0, -10.0, 4100040.0)
+
+geotiff.crs
+# <Projected CRS: EPSG:32612>
+# Name: WGS 84 / UTM zone 12N
+```
+
+For a COG, you can access the overviews, or reduced resolution versions, of the image:
+
+```py
+# Overviews are ordered from finest to coarsest resolution
+# In this case, access the second-coarsest resolution version of the image
+overview = geotiff.overviews[-2]
+```
+
+Then we can read data from the image. This loads a 512-pixel square from the
+upper-left corner of the selected overview.
+
+```py
+from async_geotiff import Window
+
+window = Window(col_off=0, row_off=0, width=512, height=512)
+array = await overview.read(window=window)
+```
+
+This `Array` instance has `data`, `mask`, and some other metadata about the fetched array data.
+
+Plot, using [`rasterio.plot.show`](https://rasterio.readthedocs.io/en/stable/api/rasterio.plot.html#rasterio.plot.show) (requires `matplotlib`):
+
+```py
+import rasterio.plot
+
+rasterio.plot.show(array.data)
+```
+
+![](assets/sentinel_2_plot.jpg)

assets/sentinel_2_plot.jpg

@@ -0,0 +1 @@
+../../assets/sentinel_2_plot.jpg

docs/assets/sentinel_2_plot.jpg

@@ -93,9 +93,6 @@ plugins:
         python:
           paths: [src]
           options:
-            # We set allow_inspection: false to ensure that all docstrings come
-            # from the pyi files, not the Rust-facing doc comments.
-            allow_inspection: false
             docstring_section_style: list
             docstring_style: google
             inherited_members: true

mkdocs.yml

@@ -43,6 +43,7 @@ dev = [
     "build>=1.4.0",
     "ipykernel>=7.1.0",
     "jsonschema>=4.26.0",
+    "matplotlib>=3.10.8",
     "morecantile>=7.0.2",
     "obstore>=0.8.2",
     "pydantic>=2.12.5",
@@ -52,6 +53,8 @@ dev = [
     "types-jsonschema>=4.26.0.20260109",
 ]
 docs = [
+    # Workaround for https://github.com/mkdocs/mkdocs/issues/4032
+    "click<8.3",
     "mkdocs-material[imaging]>=9.5.49",
     "mkdocs>=1.6.1",
     "mkdocstrings[python]>=1.0",
@@ -76,6 +79,7 @@ module = [
     # https://github.com/rasterio/affine/issues/135
     "affine.*",
     "async_tiff.store.*",
+    "rasterio.*",
 ]
 ignore_missing_imports = true
 
@@ -92,9 +96,10 @@ ignore = [
 
 [tool.ruff.lint.per-file-ignores]
 "tests/*" = [
-    "ANN001", # annotation in function argument
-    "ANN201", # return type annotation
-    "S101",   # assert
-    "SLF001", # private member access
-    "D",      # docstring
+    "ANN001",  # annotation in function argument
+    "ANN201",  # return type annotation
+    "PLR2004", # Magic value used in comparison
+    "S101",    # assert
+    "SLF001",  # private member access
+    "D",       # docstring
 ]

pyproject.toml

@@ -3,9 +3,20 @@
 [cogeo]: https://cogeo.org/
 """
 
+from . import exceptions
 from ._array import Array
 from ._geotiff import GeoTIFF
 from ._overview import Overview
+from ._tile import Tile
 from ._version import __version__
+from ._windows import Window
 
-__all__ = ["Array", "GeoTIFF", "Overview", "__version__"]
+__all__ = [
+    "Array",
+    "GeoTIFF",
+    "Overview",
+    "Tile",
+    "Window",
+    "__version__",
+    "exceptions",
+]

src/async_geotiff/__init__.py

@@ -5,7 +5,8 @@
 
 from affine import Affine
 
-from async_geotiff import Array
+from async_geotiff._array import Array
+from async_geotiff._tile import Tile
 from async_geotiff._transform import HasTransform
 
 if TYPE_CHECKING:
@@ -63,7 +64,7 @@ async def fetch_tile(
         self: HasTiffReference,
         x: int,
         y: int,
-    ) -> Array:
+    ) -> Tile:
         tile_fut = self._ifd.fetch_tile(x, y)
 
         mask_data: AsyncTiffArray | None = None
@@ -80,20 +81,26 @@ async def fetch_tile(
             y * self.tile_height,
         )
 
-        return Array._create(  # noqa: SLF001
+        array = Array._create(  # noqa: SLF001
             data=tile_data,
             mask=mask_data,
             planar_configuration=self._ifd.planar_configuration,
             crs=self.crs,
             transform=tile_transform,
             nodata=self.nodata,
         )
+        return Tile(
+            x=x,
+            y=y,
+            _ifd=self._ifd,
+            array=array,
+        )
 
     async def fetch_tiles(
         self: HasTiffReference,
         xs: list[int],
         ys: list[int],
-    ) -> list[Array]:
+    ) -> list[Tile]:
         """Fetch multiple tiles from this overview.
 
         Args:
@@ -116,7 +123,7 @@ async def fetch_tiles(
             tiles = await tiles_fut
             decoded_tiles = await asyncio.gather(*[tile.decode() for tile in tiles])
 
-        arrays: list[Array] = []
+        final_tiles: list[Tile] = []
         for x, y, tile_data, mask_data in zip(
             xs,
             ys,
@@ -136,6 +143,12 @@ async def fetch_tiles(
                 transform=tile_transform,
                 nodata=self.nodata,
             )
-            arrays.append(array)
+            tile = Tile(
+                x=x,
+                y=y,
+                _ifd=self._ifd,
+                array=array,
+            )
+            final_tiles.append(tile)
 
-        return arrays
+        return final_tiles

src/async_geotiff/_fetch.py

@@ -11,6 +11,7 @@
 from async_geotiff._crs import crs_from_geo_keys
 from async_geotiff._fetch import FetchTileMixin
 from async_geotiff._overview import Overview
+from async_geotiff._read import ReadMixin
 from async_geotiff._transform import TransformMixin
 from async_geotiff.colormap import Colormap
 
@@ -23,7 +24,7 @@
 
 
 @dataclass(frozen=True, init=False, kw_only=True, repr=False)
-class GeoTIFF(FetchTileMixin, TransformMixin):
+class GeoTIFF(ReadMixin, FetchTileMixin, TransformMixin):
     """A class representing a GeoTIFF image."""
 
     _crs: CRS | None = None
@@ -272,7 +273,14 @@ def nodata(self) -> float | None:
 
     @property
     def overviews(self) -> list[Overview]:
-        """A list of overview levels for the dataset."""
+        """A list of overview levels for the dataset.
+
+        Overviews are reduced-resolution versions of the main image used for faster
+        rendering at lower zoom levels.
+
+        This list of overviews is ordered from finest to coarsest resolution. The first
+        element of the list is the highest-resolution after the base image.
+        """
         return self._overviews
 
     @property

src/async_geotiff/_geotiff.py

@@ -6,6 +6,7 @@
 from affine import Affine
 
 from async_geotiff._fetch import FetchTileMixin
+from async_geotiff._read import ReadMixin
 from async_geotiff._transform import TransformMixin
 
 if TYPE_CHECKING:
@@ -18,7 +19,7 @@
 
 
 @dataclass(init=False, frozen=True, kw_only=True, eq=False, repr=False)
-class Overview(FetchTileMixin, TransformMixin):
+class Overview(ReadMixin, FetchTileMixin, TransformMixin):
     """An overview level of a Cloud-Optimized GeoTIFF image."""
 
     _geotiff: GeoTIFF