async-geotiff 0.1.0b3__tar.gz → 0.1.0b5__tar.gz

async_geotiff-0.1.0b5/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: async-geotiff
+Version: 0.1.0b5
+Summary: Async GeoTIFF reader for Python
+Keywords: geotiff,tiff,async,cog,raster,gis
+Author: Kyle Barron
+Author-email: Kyle Barron <kyle@developmentseed.org>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Typing :: Typed
+Requires-Dist: affine>=2.4.0
+Requires-Dist: async-tiff>=0.5.0b3
+Requires-Dist: numpy>=2.0
+Requires-Dist: pyproj>=3.3.0
+Requires-Dist: morecantile>=7.0,<8.0 ; extra == 'morecantile'
+Requires-Python: >=3.11
+Project-URL: Changelog, https://github.com/developmentseed/async-geotiff/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://developmentseed.github.io/async-geotiff/
+Project-URL: Homepage, https://github.com/developmentseed/async-geotiff
+Project-URL: Issues, https://github.com/developmentseed/async-geotiff/issues
+Project-URL: Repository, https://github.com/developmentseed/async-geotiff
+Provides-Extra: morecantile
+Description-Content-Type: text/markdown
+
+# async-geotiff
+
+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/
+
+## Features
+
+- 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.
+
+**Anti-Features** (features explicitly not in scope):
+
+- 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)

async_geotiff-0.1.0b5/README.md

@@ -0,0 +1,95 @@
+# async-geotiff
+
+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/
+
+## Features
+
+- 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.
+
+**Anti-Features** (features explicitly not in scope):
+
+- 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)

{async_geotiff-0.1.0b3 → async_geotiff-0.1.0b5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "async-geotiff"
-version = "0.1.0-beta.3"
+version = "0.1.0-beta.5"
 description = "Async GeoTIFF reader for Python"
 readme = "README.md"
 authors = [{ name = "Kyle Barron", email = "kyle@developmentseed.org" }]
@@ -22,7 +22,7 @@ classifiers = [
 keywords = ["geotiff", "tiff", "async", "cog", "raster", "gis"]
 dependencies = [
     "affine>=2.4.0",
-    "async-tiff>=0.4.0",
+    "async-tiff>=0.5.0-beta.3",
     "numpy>=2.0",
     "pyproj>=3.3.0",
 ]
@@ -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",
@@ -51,6 +52,19 @@ dev = [
     "rasterio>=1.4.4",
     "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",
+    "mike>=2.1.3",
+    "griffe-inherited-docstrings>=1.0.1",
+    # We use ruff format ourselves, but mkdocstrings requires black to be
+    # installed to format signatures in the docs
+    "black>=26",
+]
+
 
 [build-system]
 requires = ["uv_build>=0.8.8,<0.9.0"]
@@ -65,6 +79,7 @@ module = [
     # https://github.com/rasterio/affine/issues/135
     "affine.*",
     "async_tiff.store.*",
+    "rasterio.*",
 ]
 ignore_missing_imports = true
 
@@ -81,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
 ]

async_geotiff-0.1.0b5/src/async_geotiff/__init__.py

@@ -0,0 +1,22 @@
+"""Async GeoTIFF and [Cloud-Optimized GeoTIFF][cogeo] (COG) reader for Python.
+
+[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",
+    "Tile",
+    "Window",
+    "__version__",
+    "exceptions",
+]

async_geotiff-0.1.0b5/src/async_geotiff/_array.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Self
+
+import numpy as np
+from async_tiff.enums import PlanarConfiguration
+from numpy.ma import MaskedArray
+
+from async_geotiff._transform import TransformMixin
+
+if TYPE_CHECKING:
+    from affine import Affine
+    from async_tiff import Array as AsyncTiffArray
+    from numpy.typing import NDArray
+    from pyproj.crs import CRS
+
+
+@dataclass(frozen=True, kw_only=True, eq=False)
+class Array(TransformMixin):
+    """An array representation of data from a GeoTIFF."""
+
+    data: NDArray
+    """The array data with shape (bands, height, width)."""
+
+    mask: NDArray[np.bool_] | None
+    """The mask array with shape (height, width), if any.
+
+    Values of True indicate valid data; False indicates no data.
+    """
+
+    width: int
+    """The width of the array in pixels."""
+
+    height: int
+    """The height of the array in pixels."""
+
+    count: int
+    """The number of bands in the array."""
+
+    transform: Affine
+    """The affine transform mapping pixel coordinates to geographic coordinates."""
+
+    crs: CRS
+    """The coordinate reference system of the array."""
+
+    nodata: float | None = None
+    """The nodata value for the array, if any."""
+
+    @classmethod
+    def _create(  # noqa: PLR0913
+        cls,
+        *,
+        data: AsyncTiffArray,
+        mask: AsyncTiffArray | None,
+        planar_configuration: PlanarConfiguration,
+        transform: Affine,
+        crs: CRS,
+        nodata: float | None = None,
+    ) -> Self:
+        """Create an Array from async_tiff data.
+
+        Handles axis reordering to ensure data is always in (bands, height, width)
+        order, matching rasterio's convention.
+        """
+        data_arr = np.asarray(data, copy=False)
+        if mask is not None:
+            mask_arr = np.asarray(mask, copy=False).astype(np.bool_, copy=False)
+            assert mask_arr.ndim == 3  # noqa: S101, PLR2004
+            assert mask_arr.shape[2] == 1  # noqa: S101
+            # This assumes it's always (height, width, 1)
+            mask_arr = np.squeeze(mask_arr, axis=2)
+        else:
+            mask_arr = None
+
+        assert data_arr.ndim == 3, f"Expected 3D array, got {data_arr.ndim}D"  # noqa: S101, PLR2004
+
+        # async_tiff returns data in the native TIFF order:
+        # - Chunky (pixel interleaved): (height, width, bands)
+        # - Planar (band interleaved): (bands, height, width)
+        # We always want (bands, height, width) to match rasterio.
+        if planar_configuration == PlanarConfiguration.Chunky:
+            # Transpose from (H, W, C) to (C, H, W)
+            data_arr = np.moveaxis(data_arr, -1, 0)
+
+        count, height, width = data_arr.shape
+
+        return cls(
+            data=data_arr,
+            mask=mask_arr,
+            width=width,
+            height=height,
+            count=count,
+            transform=transform,
+            crs=crs,
+            nodata=nodata,
+        )
+
+    def as_masked(self) -> MaskedArray:
+        """Return the data as a masked array using the Array mask or nodata value.
+
+        !!! warning
+            In a numpy [`MaskedArray`][numpy.ma.MaskedArray], `True`
+            indicates invalid (masked) data and `False` indicates valid data.
+
+            This is the inverse convention of a GeoTIFF's mask. The boolean array
+            [`Array.mask`][async_geotiff.Array.mask] uses `True` for valid data and
+            `False` for invalid data.
+
+        Returns:
+            A masked array with the same shape as `data`, where invalid data
+                (as indicated by the mask) is masked out.
+
+        """
+        if self.mask is not None:
+            return MaskedArray(self.data, mask=~self.mask)
+
+        if self.nodata is not None:
+            return np.ma.masked_equal(self.data, self.nodata)
+
+        return MaskedArray(self.data)

async_geotiff-0.1.0b5/src/async_geotiff/_fetch.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Protocol
+
+from affine import Affine
+
+from async_geotiff._array import Array
+from async_geotiff._tile import Tile
+from async_geotiff._transform import HasTransform
+
+if TYPE_CHECKING:
+    from async_tiff import TIFF, ImageFileDirectory
+    from async_tiff import Array as AsyncTiffArray
+    from pyproj import CRS
+
+
+class HasTiffReference(HasTransform, Protocol):
+    """Protocol for objects that hold a TIFF reference and can request tiles."""
+
+    @property
+    def _ifd(self) -> ImageFileDirectory:
+        """The data IFD for this image (index, IFD)."""
+        ...
+
+    @property
+    def _mask_ifd(self) -> ImageFileDirectory | None:
+        """The mask IFD for this image (index, IFD), if any."""
+        ...
+
+    @property
+    def _tiff(self) -> TIFF:
+        """A reference to the underlying TIFF object."""
+        ...
+
+    @property
+    def crs(self) -> CRS:
+        """The coordinate reference system."""
+        ...
+
+    @property
+    def tile_height(self) -> int:
+        """The height of tiles in pixels."""
+        ...
+
+    @property
+    def tile_width(self) -> int:
+        """The width of tiles in pixels."""
+        ...
+
+    @property
+    def nodata(self) -> int | float | None:
+        """The nodata value for the image, if any."""
+        ...
+
+
+class FetchTileMixin:
+    """Mixin for fetching tiles from a GeoTIFF.
+
+    Classes using this mixin must implement HasTiffReference.
+    """
+
+    async def fetch_tile(
+        self: HasTiffReference,
+        x: int,
+        y: int,
+    ) -> Tile:
+        tile_fut = self._ifd.fetch_tile(x, y)
+
+        mask_data: AsyncTiffArray | None = None
+        if self._mask_ifd is not None:
+            mask_fut = self._mask_ifd.fetch_tile(x, y)
+            tile, mask = await asyncio.gather(tile_fut, mask_fut)
+            tile_data, mask_data = await asyncio.gather(tile.decode(), mask.decode())
+        else:
+            tile = await tile_fut
+            tile_data = await tile.decode()
+
+        tile_transform = self.transform * Affine.translation(
+            x * self.tile_width,
+            y * self.tile_height,
+        )
+
+        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[Tile]:
+        """Fetch multiple tiles from this overview.
+
+        Args:
+            xs: The x coordinates of the tiles.
+            ys: The y coordinates of the tiles.
+
+        """
+        tiles_fut = self._ifd.fetch_tiles(xs, ys)
+
+        decoded_masks: list[AsyncTiffArray | None] = [None] * len(xs)
+        if self._mask_ifd is not None:
+            masks_fut = self._mask_ifd.fetch_tiles(xs, ys)
+            tiles, masks = await asyncio.gather(tiles_fut, masks_fut)
+
+            decoded_tile_futs = [tile.decode() for tile in tiles]
+            decoded_mask_futs = [mask.decode() for mask in masks]
+            decoded_tiles = await asyncio.gather(*decoded_tile_futs)
+            decoded_masks = await asyncio.gather(*decoded_mask_futs)
+        else:
+            tiles = await tiles_fut
+            decoded_tiles = await asyncio.gather(*[tile.decode() for tile in tiles])
+
+        final_tiles: list[Tile] = []
+        for x, y, tile_data, mask_data in zip(
+            xs,
+            ys,
+            decoded_tiles,
+            decoded_masks,
+            strict=True,
+        ):
+            tile_transform = self.transform * Affine.translation(
+                x * self.tile_width,
+                y * self.tile_height,
+            )
+            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,
+            )
+            tile = Tile(
+                x=x,
+                y=y,
+                _ifd=self._ifd,
+                array=array,
+            )
+            final_tiles.append(tile)
+
+        return final_tiles