async-geotiff 0.1.0b4__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.0b4 → async_geotiff-0.1.0b5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "async-geotiff"
-version = "0.1.0-beta.4"
+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.5.0-beta.1",
+    "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",
@@ -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
 ]

{async_geotiff-0.1.0b4 → async_geotiff-0.1.0b5}/src/async_geotiff/__init__.py

@@ -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",
+]

{async_geotiff-0.1.0b4 → async_geotiff-0.1.0b5}/src/async_geotiff/_array.py

@@ -5,6 +5,7 @@ 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
 
@@ -43,8 +44,11 @@ class Array(TransformMixin):
     crs: CRS
     """The coordinate reference system of the array."""
 
+    nodata: float | None = None
+    """The nodata value for the array, if any."""
+
     @classmethod
-    def _create(
+    def _create(  # noqa: PLR0913
         cls,
         *,
         data: AsyncTiffArray,
@@ -52,22 +56,12 @@ class Array(TransformMixin):
         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.
-
-        Args:
-            data: The decoded tile data from async_tiff.
-            mask: The decoded mask data from async_tiff, if any.
-            planar_configuration: The planar configuration of the source IFD.
-            transform: The affine transform for this tile.
-            crs: The coordinate reference system.
-
-        Returns:
-            An Array with data in (bands, height, width) order.
-
         """
         data_arr = np.asarray(data, copy=False)
         if mask is not None:
@@ -99,4 +93,29 @@ class Array(TransformMixin):
             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.0b4 → async_geotiff-0.1.0b5}/src/async_geotiff/_fetch.py

@@ -5,27 +5,26 @@ from typing import TYPE_CHECKING, Protocol
 
 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:
-    from async_tiff import TIFF
+    from async_tiff import TIFF, ImageFileDirectory
     from async_tiff import Array as AsyncTiffArray
     from pyproj import CRS
 
-    from async_geotiff._ifd import IFDReference
-
 
 class HasTiffReference(HasTransform, Protocol):
     """Protocol for objects that hold a TIFF reference and can request tiles."""
 
     @property
-    def _ifd(self) -> IFDReference:
+    def _ifd(self) -> ImageFileDirectory:
         """The data IFD for this image (index, IFD)."""
         ...
 
     @property
-    def _mask_ifd(self) -> IFDReference | None:
+    def _mask_ifd(self) -> ImageFileDirectory | None:
         """The mask IFD for this image (index, IFD), if any."""
         ...
 
@@ -49,6 +48,11 @@ class HasTiffReference(HasTransform, Protocol):
         """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.
@@ -60,13 +64,12 @@ class FetchTileMixin:
         self: HasTiffReference,
         x: int,
         y: int,
-    ) -> Array:
-        tile_fut = self._tiff.fetch_tile(x, y, self._ifd.index)
+    ) -> Tile:
+        tile_fut = self._ifd.fetch_tile(x, y)
 
         mask_data: AsyncTiffArray | None = None
         if self._mask_ifd is not None:
-            mask_ifd_index = self._mask_ifd.index
-            mask_fut = self._tiff.fetch_tile(x, y, mask_ifd_index)
+            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:
@@ -78,19 +81,26 @@ class FetchTileMixin:
             y * self.tile_height,
         )
 
-        return Array._create(  # noqa: SLF001
+        array = Array._create(  # noqa: SLF001
             data=tile_data,
             mask=mask_data,
-            planar_configuration=self._ifd.ifd.planar_configuration,
+            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:
@@ -98,12 +108,11 @@ class FetchTileMixin:
             ys: The y coordinates of the tiles.
 
         """
-        tiles_fut = self._tiff.fetch_tiles(xs, ys, self._ifd.index)
+        tiles_fut = self._ifd.fetch_tiles(xs, ys)
 
         decoded_masks: list[AsyncTiffArray | None] = [None] * len(xs)
         if self._mask_ifd is not None:
-            mask_ifd_index = self._mask_ifd.index
-            masks_fut = self._tiff.fetch_tiles(xs, ys, mask_ifd_index)
+            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]
@@ -114,7 +123,7 @@ class FetchTileMixin:
             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,
@@ -129,10 +138,17 @@ class FetchTileMixin:
             array = Array._create(  # noqa: SLF001
                 data=tile_data,
                 mask=mask_data,
-                planar_configuration=self._ifd.ifd.planar_configuration,
+                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,
             )
-            arrays.append(array)
+            final_tiles.append(tile)
 
-        return arrays
+        return final_tiles

{async_geotiff-0.1.0b4 → async_geotiff-0.1.0b5}/src/async_geotiff/_geotiff.py

@@ -10,9 +10,10 @@ from async_tiff.enums import PhotometricInterpretation
 
 from async_geotiff._crs import crs_from_geo_keys
 from async_geotiff._fetch import FetchTileMixin
-from async_geotiff._ifd import IFDReference
 from async_geotiff._overview import Overview
+from async_geotiff._read import ReadMixin
 from async_geotiff._transform import TransformMixin
+from async_geotiff.colormap import Colormap
 
 if TYPE_CHECKING:
     from async_tiff import GeoKeyDirectory, ImageFileDirectory, ObspecInput
@@ -23,7 +24,7 @@ if TYPE_CHECKING:
 
 
 @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
@@ -37,16 +38,14 @@ class GeoTIFF(FetchTileMixin, TransformMixin):
     """The underlying async-tiff TIFF instance that we wrap.
     """
 
-    _primary_ifd: IFDReference = field(init=False)
+    _primary_ifd: ImageFileDirectory = field(init=False)
     """The primary (first) IFD of the GeoTIFF.
 
     Some tags, like most geo tags, only exist on the primary IFD.
     """
 
-    _mask_ifd: IFDReference | None = None
+    _mask_ifd: ImageFileDirectory | None = None
     """The mask IFD of the full-resolution GeoTIFF, if any.
-
-    (positional index of the IFD in the TIFF file, IFD object)
     """
 
     _gkd: GeoKeyDirectory = field(init=False)
@@ -58,7 +57,7 @@ class GeoTIFF(FetchTileMixin, TransformMixin):
     """
 
     @property
-    def _ifd(self) -> IFDReference:
+    def _ifd(self) -> ImageFileDirectory:
         """An alias for the primary IFD to satisfy _fetch protocol."""
         return self._primary_ifd
 
@@ -76,20 +75,20 @@ class GeoTIFF(FetchTileMixin, TransformMixin):
 
         # We use object.__setattr__ because the dataclass is frozen
         object.__setattr__(self, "_tiff", tiff)
-        object.__setattr__(self, "_primary_ifd", IFDReference(index=0, ifd=first_ifd))
+        object.__setattr__(self, "_primary_ifd", first_ifd)
         object.__setattr__(self, "_gkd", gkd)
 
         # Separate data IFDs and mask IFDs (skip the primary IFD at index 0)
         # Data IFDs are indexed by (width, height) for matching with masks
-        data_ifds: dict[tuple[int, int], IFDReference] = {}
-        mask_ifds: dict[tuple[int, int], IFDReference] = {}
+        data_ifds: dict[tuple[int, int], ImageFileDirectory] = {}
+        mask_ifds: dict[tuple[int, int], ImageFileDirectory] = {}
 
-        for idx, ifd in enumerate(tiff.ifds[1:], start=1):
+        for ifd in tiff.ifds[1:]:
             dims = (ifd.image_width, ifd.image_height)
             if is_mask_ifd(ifd):
-                mask_ifds[dims] = IFDReference(index=idx, ifd=ifd)
+                mask_ifds[dims] = ifd
             else:
-                data_ifds[dims] = IFDReference(index=idx, ifd=ifd)
+                data_ifds[dims] = ifd
 
         # Find and set the mask for the primary IFD (matches primary dimensions)
         if primary_mask_ifd := mask_ifds.get(
@@ -192,23 +191,18 @@ class GeoTIFF(FetchTileMixin, TransformMixin):
         # https://github.com/developmentseed/async-geotiff/issues/12
         raise NotImplementedError
 
-    def colormap(self, bidx: int) -> dict[int, tuple[int, int, int]]:
-        """Return a dict containing the colormap for a band.
-
-        Args:
-            bidx: The 1-based index of the band whose colormap will be returned.
+    @property
+    def colormap(self) -> Colormap | None:
+        """Return the Colormap stored in the file, if any.
 
         Returns:
-            Mapping of color index value (starting at 0) to RGBA color as a
-            4-element tuple.
-
-        Raises:
-            ValueError: If no colormap is found for the specified band (NULL color
-                table).
-            IndexError: If no band exists for the provided index.
+            A Colormap instance if the dataset has a colormap, else None.
 
         """
-        raise NotImplementedError
+        if upstream_colormap := self._primary_ifd.colormap:
+            return Colormap(_cmap=upstream_colormap, _nodata=self.nodata)
+
+        return None
 
     @property
     def compression(self) -> Compression:
@@ -247,14 +241,14 @@ class GeoTIFF(FetchTileMixin, TransformMixin):
     @property
     def height(self) -> int:
         """The height (number of rows) of the full image."""
-        return self._primary_ifd.ifd.image_height
+        return self._primary_ifd.image_height
 
     def indexes(self) -> list[int]:
         """Return the 1-based indexes of each band in the dataset.
 
         For a 3-band dataset, this property will be [1, 2, 3].
         """
-        return list(range(1, self._primary_ifd.ifd.samples_per_pixel + 1))
+        return list(range(1, self._primary_ifd.samples_per_pixel + 1))
 
     @property
     def interleaving(self) -> Interleaving:
@@ -271,7 +265,7 @@ class GeoTIFF(FetchTileMixin, TransformMixin):
     @property
     def nodata(self) -> float | None:
         """The dataset's single nodata value."""
-        nodata = self._primary_ifd.ifd.gdal_nodata
+        nodata = self._primary_ifd.gdal_nodata
         if nodata is None:
             return None
 
@@ -279,7 +273,14 @@ class GeoTIFF(FetchTileMixin, TransformMixin):
 
     @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
@@ -303,12 +304,12 @@ class GeoTIFF(FetchTileMixin, TransformMixin):
     @property
     def tile_height(self) -> int:
         """The height in pixels per tile of the image."""
-        return self._primary_ifd.ifd.tile_height or self.height
+        return self._primary_ifd.tile_height or self.height
 
     @property
     def tile_width(self) -> int:
         """The width in pixels per tile of the image."""
-        return self._primary_ifd.ifd.tile_width or self.width
+        return self._primary_ifd.tile_width or self.width
 
     @property
     def transform(self) -> Affine:
@@ -317,8 +318,8 @@ class GeoTIFF(FetchTileMixin, TransformMixin):
         This transform maps pixel row/column coordinates to coordinates in the dataset's
         CRS.
         """
-        if (tie_points := self._primary_ifd.ifd.model_tiepoint) and (
-            model_scale := self._primary_ifd.ifd.model_pixel_scale
+        if (tie_points := self._primary_ifd.model_tiepoint) and (
+            model_scale := self._primary_ifd.model_pixel_scale
         ):
             x_origin = tie_points[3]
             y_origin = tie_points[4]
@@ -327,7 +328,7 @@ class GeoTIFF(FetchTileMixin, TransformMixin):
 
             return Affine(x_resolution, 0, x_origin, 0, y_resolution, y_origin)
 
-        if model_transformation := self._primary_ifd.ifd.model_transformation:
+        if model_transformation := self._primary_ifd.model_transformation:
             # ModelTransformation is a 4x4 matrix in row-major order
             # [0  1  2  3 ]   [a  b  0  c]
             # [4  5  6  7 ] = [d  e  0  f]
@@ -358,7 +359,7 @@ class GeoTIFF(FetchTileMixin, TransformMixin):
     @property
     def width(self) -> int:
         """The width (number of columns) of the full image."""
-        return self._primary_ifd.ifd.image_width
+        return self._primary_ifd.image_width
 
 
 def has_geokeys(ifd: ImageFileDirectory) -> bool:

{async_geotiff-0.1.0b4 → async_geotiff-0.1.0b5}/src/async_geotiff/_overview.py

@@ -6,20 +6,20 @@ from typing import TYPE_CHECKING
 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:
-    from async_tiff import TIFF, GeoKeyDirectory
+    from async_tiff import TIFF, GeoKeyDirectory, ImageFileDirectory
     from pyproj.crs import CRS
 
     from async_geotiff import GeoTIFF
-    from async_geotiff._ifd import IFDReference
 
 # ruff: noqa: SLF001
 
 
 @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
@@ -30,13 +30,13 @@ class Overview(FetchTileMixin, TransformMixin):
     """The GeoKeyDirectory of the primary IFD.
     """
 
-    _ifd: IFDReference
+    _ifd: ImageFileDirectory
     """The IFD for this overview level.
 
     (positional index of the IFD in the TIFF file, IFD object)
     """
 
-    _mask_ifd: IFDReference | None
+    _mask_ifd: ImageFileDirectory | None
     """The IFD for the mask associated with this overview level, if any.
 
     (positional index of the IFD in the TIFF file, IFD object)
@@ -48,8 +48,8 @@ class Overview(FetchTileMixin, TransformMixin):
         *,
         geotiff: GeoTIFF,
         gkd: GeoKeyDirectory,
-        ifd: IFDReference,
-        mask_ifd: IFDReference | None,
+        ifd: ImageFileDirectory,
+        mask_ifd: ImageFileDirectory | None,
     ) -> Overview:
         instance = cls.__new__(cls)
 
@@ -74,17 +74,22 @@ class Overview(FetchTileMixin, TransformMixin):
     @property
     def height(self) -> int:
         """The height of the overview in pixels."""
-        return self._ifd.ifd.image_height
+        return self._ifd.image_height
+
+    @property
+    def nodata(self) -> int | float | None:
+        """The nodata value for the overview, if any."""
+        return self._geotiff.nodata
 
     @property
     def tile_height(self) -> int:
         """The height in pixels per tile of the overview."""
-        return self._ifd.ifd.tile_height or self.height
+        return self._ifd.tile_height or self.height
 
     @property
     def tile_width(self) -> int:
         """The width in pixels per tile of the overview."""
-        return self._ifd.ifd.tile_width or self.width
+        return self._ifd.tile_width or self.width
 
     @property
     def transform(self) -> Affine:  # type: ignore[override]
@@ -96,9 +101,9 @@ class Overview(FetchTileMixin, TransformMixin):
         """
         full_transform = self._geotiff.transform
 
-        overview_width = self._ifd.ifd.image_width
+        overview_width = self._ifd.image_width
         full_width = self._geotiff.width
-        overview_height = self._ifd.ifd.image_height
+        overview_height = self._ifd.image_height
         full_height = self._geotiff.height
 
         scale_x = full_width / overview_width
@@ -109,4 +114,4 @@ class Overview(FetchTileMixin, TransformMixin):
     @property
     def width(self) -> int:
         """The width of the overview in pixels."""
-        return self._ifd.ifd.image_width
+        return self._ifd.image_width

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

@@ -0,0 +1,185 @@
+"""Higher-level read utilities for cross-tile operations."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol
+
+import numpy as np
+from affine import Affine
+
+from async_geotiff._array import Array
+from async_geotiff._fetch import HasTiffReference
+from async_geotiff._windows import Window
+from async_geotiff.exceptions import WindowError
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+    from async_geotiff._tile import Tile
+
+
+class CanFetchTiles(HasTiffReference, Protocol):
+    """Protocol for objects that can fetch tiles."""
+
+    @property
+    def height(self) -> int:
+        """The height of the image in pixels."""
+        ...
+
+    @property
+    def width(self) -> int:
+        """The width of the image in pixels."""
+        ...
+
+    async def fetch_tiles(
+        self,
+        xs: list[int],
+        ys: list[int],
+    ) -> list[Tile]: ...
+
+
+class ReadMixin:
+    async def read(
+        self: CanFetchTiles,
+        *,
+        window: Window | None = None,
+    ) -> Array:
+        """Read pixel data for a window region.
+
+        This method fetches all tiles that intersect the given window and
+        stitches them together, returning only the pixels within the window.
+
+        Args:
+            window: A Window object defining the pixel region to read.
+                If None, the entire image is read.
+
+        Returns:
+            An Array containing the pixel data for the requested window.
+
+        Raises:
+            WindowError: If the window extends outside the image bounds.
+
+        """
+        return await read(self, window=window)
+
+
+async def read(
+    self: CanFetchTiles,
+    *,
+    window: Window | None = None,
+) -> Array:
+    if isinstance(window, Window):
+        win = window
+    else:
+        win = Window(col_off=0, row_off=0, width=self.width, height=self.height)
+
+    # Most validation occurred in construction of Window; here we just check against
+    # image size
+    if win.col_off + win.width > self.width or win.row_off + win.height > self.height:
+        raise WindowError(
+            f"Window extends outside image bounds.\n"
+            f"Window: cols={win.col_off}:{win.col_off + win.width}, "
+            f"rows={win.row_off}:{win.row_off + win.height}.\n"
+            f"Image size: {self.height}x{self.width}",
+        )
+
+    # Calculate which tiles we need to fetch
+    tile_x_start = win.col_off // self.tile_width
+    tile_x_stop = (win.col_off + win.width - 1) // self.tile_width + 1
+    tile_y_start = win.row_off // self.tile_height
+    tile_y_stop = (win.row_off + win.height - 1) // self.tile_height + 1
+
+    # Build list of tile coordinates
+    xs: list[int] = []
+    ys: list[int] = []
+    for tx in range(tile_x_start, tile_x_stop):
+        for ty in range(tile_y_start, tile_y_stop):
+            xs.append(tx)
+            ys.append(ty)
+
+    tiles = await self.fetch_tiles(xs, ys)
+
+    num_bands = tiles[0].array.count
+    dtype = tiles[0].array.data.dtype
+
+    # Create output array and mask array
+    output_data = np.empty((num_bands, win.height, win.width), dtype=dtype)
+    output_mask: NDArray[np.bool_] | None = None
+    if self._mask_ifd is not None:
+        output_mask = np.ones((win.height, win.width), dtype=np.bool_)
+
+    assemble_tiles(
+        tiles=tiles,
+        window=win,
+        tile_width=self.tile_width,
+        tile_height=self.tile_height,
+        output_data=output_data,
+        output_mask=output_mask,
+    )
+
+    window_transform = self.transform * Affine.translation(
+        win.col_off,
+        win.row_off,
+    )
+
+    return Array(
+        data=output_data,
+        mask=output_mask,
+        width=win.width,
+        height=win.height,
+        count=num_bands,
+        transform=window_transform,
+        crs=self.crs,
+    )
+
+
+def assemble_tiles(  # noqa: PLR0913
+    *,
+    tiles: list[Tile],
+    window: Window,
+    tile_width: int,
+    tile_height: int,
+    output_data: NDArray[np.generic],
+    output_mask: NDArray[np.bool_] | None,
+) -> None:
+    """Assemble multiple tiles into output arrays.
+
+    This function copies data from tiles into the appropriate positions
+    in the output arrays, handling partial tiles at window boundaries.
+    """
+    for tile in tiles:
+        # Create a window for this tile's position in image coordinates
+        tile_window = Window(
+            col_off=tile.x * tile_width,
+            row_off=tile.y * tile_height,
+            width=tile.array.width,
+            height=tile.array.height,
+        )
+
+        # Calculate the intersection between tile and target window
+        overlap = window.intersection(tile_window)
+
+        # Calculate source slice within the tile
+        src_col_start = overlap.col_off - tile_window.col_off
+        src_col_stop = src_col_start + overlap.width
+        src_row_start = overlap.row_off - tile_window.row_off
+        src_row_stop = src_row_start + overlap.height
+
+        # Calculate destination slice within the output
+        dst_col_start = overlap.col_off - window.col_off
+        dst_col_stop = dst_col_start + overlap.width
+        dst_row_start = overlap.row_off - window.row_off
+        dst_row_stop = dst_row_start + overlap.height
+
+        # Copy data and mask if present
+        output_data[
+            :,
+            dst_row_start:dst_row_stop,
+            dst_col_start:dst_col_stop,
+        ] = tile.array.data[:, src_row_start:src_row_stop, src_col_start:src_col_stop]
+
+        if output_mask is not None and tile.array.mask is not None:
+            output_mask[
+                dst_row_start:dst_row_stop,
+                dst_col_start:dst_col_stop,
+            ] = tile.array.mask[src_row_start:src_row_stop, src_col_start:src_col_stop]

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

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from async_tiff import ImageFileDirectory
+
+    from async_geotiff._array import Array
+
+
+@dataclass(frozen=True, kw_only=True, eq=False)
+class Tile:
+    """A tile from a GeoTIFF, containing array data and grid position."""
+
+    x: int
+    """The tile column index in the GeoTIFF or overview."""
+
+    y: int
+    """The tile row index in the GeoTIFF or overview."""
+
+    _ifd: ImageFileDirectory
+    """A reference to the IFD this tile belongs to."""
+
+    array: Array
+    """The array data for this tile."""

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

@@ -0,0 +1,76 @@
+"""Window utilities for defining rectangular subsets of rasters."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from async_geotiff.exceptions import WindowError
+
+
+@dataclass(frozen=True, slots=True)
+class Window:
+    """A rectangular subset of a raster.
+
+    Windows define pixel regions using column/row offsets and dimensions.
+    This class is similar to rasterio's [Window][rasterio.windows.Window] but supports
+    integer offsets and ranges only.
+    """
+
+    col_off: int
+    """The column offset (x position of the left edge)."""
+
+    row_off: int
+    """The row offset (y position of the top edge)."""
+
+    width: int
+    """The width in pixels (number of columns)."""
+
+    height: int
+    """The height in pixels (number of rows)."""
+
+    def __post_init__(self) -> None:
+        """Validate window dimensions."""
+        if self.col_off < 0 or self.row_off < 0:
+            raise WindowError(
+                f"Window start indices must be non-negative, "
+                f"got col_off={self.col_off}, row_off={self.row_off}",
+            )
+
+        if self.width <= 0:
+            raise WindowError(f"Window width must be positive, got {self.width}")
+
+        if self.height <= 0:
+            raise WindowError(f"Window height must be positive, got {self.height}")
+
+    def __repr__(self) -> str:
+        """Return a nicely formatted representation string."""
+        return (
+            f"async_geotiff.Window(col_off={self.col_off}, row_off={self.row_off}, "
+            f"width={self.width}, height={self.height})"
+        )
+
+    def intersection(self, other: Window) -> Window:
+        """Compute the intersection with another window.
+
+        Args:
+            other: Another Window object.
+
+        Returns:
+            A new Window representing the overlapping region.
+
+        Raises:
+            WindowError: If windows do not intersect.
+
+        """
+        col_off = max(self.col_off, other.col_off)
+        row_off = max(self.row_off, other.row_off)
+        col_stop = min(self.col_off + self.width, other.col_off + other.width)
+        row_stop = min(self.row_off + self.height, other.row_off + other.height)
+
+        width = col_stop - col_off
+        height = row_stop - row_off
+
+        if width <= 0 or height <= 0:
+            raise WindowError(f"Windows do not intersect: {self} and {other}")
+
+        return Window(col_off=col_off, row_off=row_off, width=width, height=height)

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

@@ -0,0 +1,104 @@
+"""High-level Colormap class for GeoTIFF colormaps."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from async_tiff import Colormap as AsyncTiffColormap
+    from numpy.typing import NDArray
+
+
+@dataclass(frozen=True, kw_only=True, eq=False)
+class Colormap:
+    """A representation of a GeoTIFF colormap.
+
+    GeoTIFF colormaps
+    """
+
+    _cmap: AsyncTiffColormap
+    """The colormap data held in Rust, accessible via the buffer protocol.
+
+    Has shape `(N, 3)` and is of data type uint16.
+    """
+
+    _nodata: int | float | None
+    """The nodata value from gdal_nodata, if set."""
+
+    def as_array(self, *, dtype: type[np.uint8 | np.uint16] = np.uint8) -> NDArray:
+        """Return the colormap as a NumPy array with shape (N, 3) and dtype uint16.
+
+        Each row corresponds to a color entry in the colormap, with columns
+        representing the Red, Green, and Blue components respectively.
+
+        This is the most efficient way to access and apply the colormap data.
+
+        ```py
+        geotiff = await GeoTIFF.open(...)
+        array = await geotiff.fetch_tile(0, 0)
+
+        colormap = geotiff.colormap
+        colormap_array = colormap.as_array()
+
+        rgb_data = colormap_array[array.data[0]]
+        # A 3D array with shape (height, width, 3)
+        ```
+
+        Returns:
+            A NumPy array representation of the colormap.
+
+        """
+        cmap_array = np.asarray(self._cmap)
+        if dtype == np.uint8:
+            return (cmap_array >> 8).astype(np.uint8)
+        if dtype == np.uint16:
+            return cmap_array
+        raise ValueError("dtype must be either np.uint8 or np.uint16.")
+
+    def as_dict(
+        self,
+        *,
+        dtype: type[np.uint8 | np.uint16] = np.uint8,
+    ) -> dict[int, tuple[int, int, int]]:
+        """Return the colormap as a dictionary mapping indices to RGB tuples.
+
+        Returns:
+            A dictionary where keys are indices and values are tuples of
+                (Red, Green, Blue) components.
+
+        """
+        cmap_array = self.as_array(dtype=dtype)
+        return {
+            int(idx): (int(r), int(g), int(b))
+            for idx, (r, g, b) in enumerate(cmap_array)
+        }
+
+    def as_rasterio(self) -> dict[int, tuple[int, int, int, int]]:
+        """Return the colormap as a mapping to 8-bit RGBA colors.
+
+        This returns a colormap in the same format as rasterio's
+        [`DatasetReader.colormap`][rasterio.io.DatasetReader.colormap] method.
+
+        This is the same as
+        [`Colormap.as_dict`][async_geotiff.colormap.Colormap.as_dict] with:
+
+        - `dtype` set to `np.uint8`
+        - an added alpha channel set to 255, **except** for the nodata value, if
+          defined, which has an alpha of 0.
+
+        Returns:
+            Mapping of color index value (starting at 0) to RGBA color as a 4-element
+                tuple.
+
+        """
+        cmap_array = self.as_array(dtype=np.uint8)
+        cmap_dict: dict[int, tuple[int, int, int, int]] = {}
+
+        for idx, (r, g, b) in enumerate(cmap_array):
+            alpha = 255 if self._nodata is None or idx != self._nodata else 0
+            cmap_dict[int(idx)] = (int(r), int(g), int(b), alpha)
+
+        return cmap_dict

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

@@ -0,0 +1,5 @@
+"""Exceptions for async_geotiff package."""
+
+
+class WindowError(Exception):
+    """Exception raised for window-related errors."""

{async_geotiff-0.1.0b4 → async_geotiff-0.1.0b5}/src/async_geotiff/tms.py

@@ -47,8 +47,8 @@ def generate_tms(
     bounds = geotiff.bounds
     crs = geotiff.crs
     tr = geotiff.transform
-    blockxsize = geotiff._primary_ifd.ifd.tile_width  # noqa: SLF001
-    blockysize = geotiff._primary_ifd.ifd.tile_height  # noqa: SLF001
+    blockxsize = geotiff._primary_ifd.tile_width  # noqa: SLF001
+    blockysize = geotiff._primary_ifd.tile_height  # noqa: SLF001
 
     if blockxsize is None or blockysize is None:
         raise ValueError("GeoTIFF must be tiled to generate a TMS.")
@@ -63,8 +63,8 @@ def generate_tms(
 
     for idx, overview in enumerate(reversed(geotiff.overviews)):
         overview_tr = overview.transform
-        blockxsize = overview._ifd.ifd.tile_width  # noqa: SLF001
-        blockysize = overview._ifd.ifd.tile_height  # noqa: SLF001
+        blockxsize = overview._ifd.tile_width  # noqa: SLF001
+        blockysize = overview._ifd.tile_height  # noqa: SLF001
 
         if blockxsize is None or blockysize is None:
             raise ValueError("GeoTIFF overviews must be tiled to generate a TMS.")

async_geotiff-0.1.0b4/PKG-INFO

@@ -1,53 +0,0 @@
-Metadata-Version: 2.4
-Name: async-geotiff
-Version: 0.1.0b4
-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.0b1
-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
-
-Async GeoTIFF and [Cloud-Optimized GeoTIFF][cogeo] (COG) reader for Python, wrapping [`async-tiff`][async-tiff].
-
-[async-tiff]: https://github.com/developmentseed/async-tiff
-[cogeo]: https://cogeo.org/
-
-## Project Goals:
-
-- 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.
-
-## References
-
-- aiocogeo: https://github.com/geospatial-jeff/aiocogeo

async_geotiff-0.1.0b4/README.md

@@ -1,20 +0,0 @@
-# async-geotiff
-
-Async GeoTIFF and [Cloud-Optimized GeoTIFF][cogeo] (COG) reader for Python, wrapping [`async-tiff`][async-tiff].
-
-[async-tiff]: https://github.com/developmentseed/async-tiff
-[cogeo]: https://cogeo.org/
-
-## Project Goals:
-
-- 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.
-
-## References
-
-- aiocogeo: https://github.com/geospatial-jeff/aiocogeo

async_geotiff-0.1.0b4/src/async_geotiff/_ifd.py

@@ -1,18 +0,0 @@
-from __future__ import annotations
-
-from dataclasses import dataclass
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from async_tiff import ImageFileDirectory
-
-
-@dataclass(frozen=True, kw_only=True, repr=False)
-class IFDReference:
-    """A reference to an Image File Directory (IFD) in a TIFF file."""
-
-    index: int
-    """The positional index of the IFD in the TIFF file."""
-
-    ifd: ImageFileDirectory
-    """The IFD object itself."""