async-geotiff 0.1.0b3__py3-none-any.whl → 0.1.0b5__py3-none-any.whl

async_geotiff/__init__.py

@@ -3,8 +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__ = ["GeoTIFF", "Overview", "__version__"]
+__all__ = [
+    "Array",
+    "GeoTIFF",
+    "Overview",
+    "Tile",
+    "Window",
+    "__version__",
+    "exceptions",
+]

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/_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

async_geotiff/_geotiff.py

@@ -2,28 +2,38 @@ from __future__ import annotations
 
 from dataclasses import dataclass, field
 from functools import cached_property
-from typing import TYPE_CHECKING, Literal, Self
+from typing import TYPE_CHECKING, Self
 
 from affine import Affine
 from async_tiff import TIFF
 from async_tiff.enums import PhotometricInterpretation
 
 from async_geotiff._crs import crs_from_geo_keys
+from async_geotiff._fetch import FetchTileMixin
 from async_geotiff._overview import Overview
-from async_geotiff.enums import Compression, Interleaving
+from async_geotiff._read import ReadMixin
+from async_geotiff._transform import TransformMixin
+from async_geotiff.colormap import Colormap
 
 if TYPE_CHECKING:
-    from collections.abc import Callable
-
-    import pyproj
     from async_tiff import GeoKeyDirectory, ImageFileDirectory, ObspecInput
     from async_tiff.store import ObjectStore  # type: ignore # noqa: PGH003
+    from pyproj.crs import CRS
+
+    from async_geotiff.enums import Compression, Interleaving
 
 
 @dataclass(frozen=True, init=False, kw_only=True, repr=False)
-class GeoTIFF:
+class GeoTIFF(ReadMixin, FetchTileMixin, TransformMixin):
     """A class representing a GeoTIFF image."""
 
+    _crs: CRS | None = None
+    """A cached CRS instance.
+
+    We don't use functools.cached_property on the `crs` attribute because of typing
+    issues.
+    """
+
     _tiff: TIFF
     """The underlying async-tiff TIFF instance that we wrap.
     """
@@ -34,6 +44,10 @@ class GeoTIFF:
     Some tags, like most geo tags, only exist on the primary IFD.
     """
 
+    _mask_ifd: ImageFileDirectory | None = None
+    """The mask IFD of the full-resolution GeoTIFF, if any.
+    """
+
     _gkd: GeoKeyDirectory = field(init=False)
     """The GeoKeyDirectory of the primary IFD.
     """
@@ -42,6 +56,11 @@ class GeoTIFF:
     """A list of overviews for the GeoTIFF.
     """
 
+    @property
+    def _ifd(self) -> ImageFileDirectory:
+        """An alias for the primary IFD to satisfy _fetch protocol."""
+        return self._primary_ifd
+
     def __init__(self, tiff: TIFF) -> None:
         """Create a GeoTIFF from an existing TIFF instance."""
         first_ifd = tiff.ifds[0]
@@ -59,29 +78,32 @@ class GeoTIFF:
         object.__setattr__(self, "_primary_ifd", first_ifd)
         object.__setattr__(self, "_gkd", gkd)
 
-        # Skip the first IFD, since it's the primary image
-        ifd_idx = 1
+        # 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], ImageFileDirectory] = {}
+        mask_ifds: dict[tuple[int, int], ImageFileDirectory] = {}
+
+        for ifd in tiff.ifds[1:]:
+            dims = (ifd.image_width, ifd.image_height)
+            if is_mask_ifd(ifd):
+                mask_ifds[dims] = ifd
+            else:
+                data_ifds[dims] = ifd
+
+        # Find and set the mask for the primary IFD (matches primary dimensions)
+        if primary_mask_ifd := mask_ifds.get(
+            (first_ifd.image_width, first_ifd.image_height),
+        ):
+            object.__setattr__(self, "_mask_ifd", primary_mask_ifd)
+
+        # Build overviews, sorted by resolution (highest to lowest, i.e., largest first)
+        # Sort by width * height descending
+        sorted_dims = sorted(data_ifds.keys(), key=lambda d: d[0] * d[1], reverse=True)
+
         overviews: list[Overview] = []
-        while True:
-            try:
-                data_ifd = (ifd_idx, tiff.ifds[ifd_idx])
-            except IndexError:
-                # No more IFDs
-                break
-
-            ifd_idx += 1
-
-            mask_ifd = None
-            next_ifd = None
-            try:
-                next_ifd = tiff.ifds[ifd_idx]
-            except IndexError:
-                # No more IFDs
-                pass
-            finally:
-                if next_ifd is not None and is_mask_ifd(next_ifd):
-                    mask_ifd = (ifd_idx, next_ifd)
-                    ifd_idx += 1
+        for dims in sorted_dims:
+            data_ifd = data_ifds[dims]
+            mask_ifd = mask_ifds.get(dims)
 
             ovr = Overview._create(  # noqa: SLF001
                 geotiff=self,
@@ -169,24 +191,18 @@ class GeoTIFF:
         # 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:
@@ -204,10 +220,15 @@ class GeoTIFF:
         """The number of raster bands in the full image."""
         raise NotImplementedError
 
-    @cached_property
-    def crs(self) -> pyproj.CRS:
+    @property
+    def crs(self) -> CRS:
         """The dataset's coordinate reference system."""
-        return crs_from_geo_keys(self._gkd)
+        if self._crs is not None:
+            return self._crs
+
+        crs = crs_from_geo_keys(self._gkd)
+        object.__setattr__(self, "_crs", crs)
+        return crs
 
     @property
     def dtypes(self) -> list[str]:
@@ -222,27 +243,6 @@ class GeoTIFF:
         """The height (number of rows) of the full image."""
         return self._primary_ifd.image_height
 
-    def index(
-        self,
-        x: float,
-        y: float,
-        op: Callable[[float, float], tuple[int, int]] | None = None,
-    ) -> tuple[int, int]:
-        """Get the (row, col) index of the pixel containing (x, y).
-
-        Args:
-            x: x value in coordinate reference system
-            y: y value in coordinate reference system
-            op: function, optional (default: numpy.floor)
-                Function to convert fractional pixels to whole numbers
-                (floor, ceiling, round)
-
-        Returns:
-            (row index, col index)
-
-        """
-        raise NotImplementedError
-
     def indexes(self) -> list[int]:
         """Return the 1-based indexes of each band in the dataset.
 
@@ -273,7 +273,14 @@ class GeoTIFF:
 
     @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
@@ -283,7 +290,7 @@ class GeoTIFF:
         # https://rasterio.readthedocs.io/en/stable/api/rasterio.enums.html#rasterio.enums.PhotometricInterp
         raise NotImplementedError
 
-    @cached_property
+    @property
     def res(self) -> tuple[float, float]:
         """Return the (width, height) of pixels in the units of its CRS."""
         transform = self.transform
@@ -294,7 +301,17 @@ class GeoTIFF:
         """Get the shape (height, width) of the full image."""
         return (self.height, self.width)
 
-    @cached_property
+    @property
+    def tile_height(self) -> int:
+        """The height in pixels per tile of the image."""
+        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.tile_width or self.width
+
+    @property
     def transform(self) -> Affine:
         """Return the dataset's georeferencing transformation matrix.
 
@@ -344,46 +361,6 @@ class GeoTIFF:
         """The width (number of columns) of the full image."""
         return self._primary_ifd.image_width
 
-    def xy(
-        self,
-        row: int,
-        col: int,
-        offset: Literal["center", "ul", "ur", "ll", "lr"] | str = "center",
-    ) -> tuple[float, float]:
-        """Get the coordinates x, y of a pixel at row, col.
-
-        The pixel's center is returned by default, but a corner can be returned
-        by setting `offset` to one of `"ul"`, `"ur"`, `"ll"`, `"lr"`.
-
-        Args:
-            row: Pixel row.
-            col: Pixel column.
-            offset: Determines if the returned coordinates are for the center of the
-                pixel or for a corner.
-
-        """
-        transform = self.transform
-
-        if offset == "center":
-            c = col + 0.5
-            r = row + 0.5
-        elif offset == "ul":
-            c = col
-            r = row
-        elif offset == "ur":
-            c = col + 1
-            r = row
-        elif offset == "ll":
-            c = col
-            r = row + 1
-        elif offset == "lr":
-            c = col + 1
-            r = row + 1
-        else:
-            raise ValueError(f"Invalid offset value: {offset}")
-
-        return transform * (c, r)
-
 
 def has_geokeys(ifd: ImageFileDirectory) -> bool:
     """Check if an IFD has GeoTIFF keys.
@@ -398,8 +375,7 @@ def has_geokeys(ifd: ImageFileDirectory) -> bool:
 def is_mask_ifd(ifd: ImageFileDirectory) -> bool:
     """Check if an IFD is a mask IFD."""
     return (
-        ifd.compression == Compression.deflate
-        and ifd.new_subfile_type is not None
+        ifd.new_subfile_type is not None
         and ifd.new_subfile_type & 4 != 0
         and ifd.photometric_interpretation == PhotometricInterpretation.TransparencyMask
     )