feat: GeoTIFF API scaffolding (#2)

* feat: GeoTIFF API scaffolding

* Update scaffolding

Author: kylebarron

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "fixtures/geotiff-test-data"]
+	path = fixtures/geotiff-test-data
+	url = https://github.com/developmentseed/geotiff-test-data

fixtures/geotiff-test-data

@@ -5,14 +5,22 @@ description = "Async GeoTIFF reader for Python"
 readme = "README.md"
 authors = [{ name = "Kyle Barron", email = "kyle@developmentseed.org" }]
 requires-python = ">=3.11"
-dependencies = ["async-tiff>=0.4.0-beta.1"]
+dependencies = [
+    "affine>=2.4.0",
+    "async-tiff>=0.4.0",
+    "numpy>2",
+    "pyproj>=3.7.2",
+]
 
 [project.optional-dependencies]
 morecantile = ["morecantile>=7.0,<8.0"]
 
 [dependency-groups]
-dev = ["ipykernel>=7.1.0"]
+dev = ["ipykernel>=7.1.0", "rasterio>=1.4.4"]
 
 [build-system]
 requires = ["uv_build>=0.8.8,<0.9.0"]
 build-backend = "uv_build"
+
+[tool.ruff.lint]
+select = ["I"]

pyproject.toml

@@ -1,2 +1,4 @@
-def hello() -> str:
-    return "Hello from async-geotiff!"
+from ._version import __version__
+from ._geotiff import GeoTIFF
+
+__all__ = ["GeoTIFF", "__version__"]

src/async_geotiff/__init__.py

@@ -0,0 +1,246 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal, Self
+
+from async_tiff import TIFF, ImageFileDirectory, ObspecInput
+from async_tiff.store import ObjectStore
+
+from async_geotiff.enums import Compression, Interleaving, PhotometricInterp
+
+if TYPE_CHECKING:
+    import pyproj
+    from affine import Affine
+
+
+class GeoTIFF:
+    """A class representing a GeoTIFF dataset."""
+
+    _tiff: TIFF
+    """The underlying async-tiff TIFF instance that we wrap.
+    """
+
+    def __init__(self, tiff: TIFF) -> None:
+        """Create a GeoTIFF from an existing TIFF instance."""
+        # Validate that this is indeed a GeoTIFF
+        if not has_geokeys(tiff.ifds[0]):
+            raise ValueError("TIFF does not contain GeoTIFF keys")
+
+        self._tiff = tiff
+
+    @classmethod
+    async def open(
+        cls,
+        path: str,
+        *,
+        store: ObjectStore | ObspecInput,
+        prefetch: int = 32768,
+        multiplier: int | float = 2.0,
+    ) -> Self:
+        """Open a new TIFF.
+
+        Args:
+            path: The path within the store to read from.
+            store: The backend to use for data fetching.
+            prefetch: The number of initial bytes to read up front.
+            multiplier: The multiplier to use for readahead size growth. Must be
+                greater than 1.0. For example, for a value of `2.0`, the first metadata
+                read will be of size `prefetch`, and then the next read will be of size
+                `prefetch * 2`.
+
+        Returns:
+            A TIFF instance.
+        """
+        tiff = await TIFF.open(
+            path=path, store=store, prefetch=prefetch, multiplier=multiplier
+        )
+        return cls(tiff)
+
+    @property
+    def block_shapes(self) -> list[tuple[int, int]]:
+        """An ordered list of block shapes for each bands
+
+        Shapes are tuples and have the same ordering as the dataset's shape:
+
+        - (count of image rows, count of image columns).
+        """
+        raise NotImplementedError()
+
+    def block_size(self, bidx: int, i: int, j: int) -> int:
+        """Returns the size in bytes of a particular block.
+
+        Args:
+            bidx: Band index, starting with 1.
+            i: Row index of the block, starting with 0.
+            j: Column index of the block, starting with 0.
+        """
+        raise NotImplementedError()
+
+    @property
+    def bounds(self) -> tuple[float, float, float, float]:
+        """Returns the bounds of the dataset in the units of its coordinate reference system.
+
+        Returns:
+            (lower left x, lower left y, upper right x, upper right y)
+        """
+        raise NotImplementedError()
+
+    @property
+    def colorinterp(self) -> list[str]:
+        """The color interpretation of each band in index order."""
+        # TODO: we should return an enum here. The enum should match rasterio.
+        raise NotImplementedError()
+
+    def colormap(self, bidx: int) -> dict[int, tuple[int, int, int]]:
+        """Returns a dict containing the colormap for a band.
+
+        Args:
+            bidx: The 1-based index of the band whose colormap will be returned.
+
+        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.
+
+        """
+        raise NotImplementedError()
+
+    @property
+    def compression(self) -> Compression:
+        """The compression algorithm used for the dataset."""
+        # TODO: should return an enum. The enum should match rasterio.
+        # Also, is there ever a case where overviews have a different compression from
+        # the base image?
+        # Should we diverge from rasterio and not have this as a property returning a
+        # single string?
+        raise NotImplementedError()
+
+    @property
+    def count(self) -> int:
+        """The number of raster bands in the dataset."""
+        raise NotImplementedError()
+
+    @property
+    def crs(self) -> pyproj.CRS:
+        """The dataset’s coordinate reference system."""
+        raise NotImplementedError()
+
+    @property
+    def dtypes(self) -> list[str]:
+        """The data types of each band in index order."""
+        # TODO: not sure what the return type should be. Perhaps we should define a
+        # `DataType` enum?
+        raise NotImplementedError()
+
+    @property
+    def height(self) -> int:
+        """The height (number of rows) of the dataset."""
+        raise NotImplementedError()
+
+    def index(
+        self,
+        x: float,
+        y: float,
+        op=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]:
+        """The 1-based indexes of each band in the dataset
+
+        For a 3-band dataset, this property will be [1, 2, 3].
+        """
+        raise NotImplementedError()
+
+    @property
+    def interleaving(self) -> Interleaving:
+        """The interleaving scheme of the dataset."""
+        # TODO: Should return an enum.
+        # https://rasterio.readthedocs.io/en/stable/api/rasterio.enums.html#rasterio.enums.Interleaving
+        raise NotImplementedError()
+
+    @property
+    def is_tiled(self) -> bool:
+        """Check if the dataset is tiled."""
+        raise NotImplementedError()
+
+    @property
+    def nodata(self) -> float | int | None:
+        """The dataset's single nodata value."""
+        raise NotImplementedError()
+
+    @property
+    def photometric(self) -> PhotometricInterp | None:
+        """The photometric interpretation of the dataset."""
+        # TODO: should return enum
+        # https://rasterio.readthedocs.io/en/stable/api/rasterio.enums.html#rasterio.enums.PhotometricInterp
+        raise NotImplementedError()
+
+    @property
+    def res(self) -> tuple[float, float]:
+        """Returns the (width, height) of pixels in the units of its coordinate reference system."""
+        raise NotImplementedError()
+
+    @property
+    def shape(self) -> tuple[int, int]:
+        """Get the shape (height, width) of the full image."""
+        raise NotImplementedError()
+
+    @property
+    def transform(self) -> Affine:
+        """The dataset's georeferencing transformation matrix
+
+        This transform maps pixel row/column coordinates to coordinates in the dataset's coordinate reference system.
+        """
+        raise NotImplementedError()
+
+    @property
+    def width(self) -> int:
+        """The width (number of columns) of the dataset."""
+        raise NotImplementedError()
+
+    def xy(
+        self,
+        row: int,
+        col: int,
+        offset: Literal["center", "ul", "ur", "ll", "lr"] = "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`.
+
+        Parameters:
+            row: Pixel row.
+            col: Pixel column.
+            offset: Determines if the returned coordinates are for the center of the
+                pixel or for a corner.
+
+        """
+        raise NotImplementedError()
+
+
+def has_geokeys(ifd: ImageFileDirectory) -> bool:
+    """Check if an IFD has GeoTIFF keys.
+
+    Args:
+        ifd: The IFD to check.
+
+    """
+    return ifd.geo_key_directory is not None

src/async_geotiff/_geotiff.py

@@ -0,0 +1 @@
+"""Generate a Tile Matrix Set from a GeoTIFF file, using morecantile."""

src/async_geotiff/_tms.py

@@ -0,0 +1,6 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("async-geotiff")
+except PackageNotFoundError:
+    __version__ = "uninstalled"

src/async_geotiff/_version.py

@@ -0,0 +1,55 @@
+from enum import Enum, IntEnum
+
+
+# https://github.com/rasterio/rasterio/blob/2d79e5f3a00e919ecaa9573adba34a78274ce48c/rasterio/enums.py#L153-L174
+class Compression(Enum):
+    """Available compression algorithms for GeoTIFFs.
+
+    Note that compression options for EXR, MRF, etc are not included
+    in this enum.
+    """
+
+    jpeg = "JPEG"
+    lzw = "LZW"
+    packbits = "PACKBITS"
+    deflate = "DEFLATE"
+    ccittrle = "CCITTRLE"
+    ccittfax3 = "CCITTFAX3"
+    ccittfax4 = "CCITTFAX4"
+    lzma = "LZMA"
+    none = "NONE"
+    zstd = "ZSTD"
+    lerc = "LERC"
+    lerc_deflate = "LERC_DEFLATE"
+    lerc_zstd = "LERC_ZSTD"
+    webp = "WEBP"
+    jpeg2000 = "JPEG2000"
+
+
+# https://github.com/rasterio/rasterio/blob/2d79e5f3a00e919ecaa9573adba34a78274ce48c/rasterio/enums.py#L177-L182
+class Interleaving(Enum):
+    pixel = "PIXEL"
+    line = "LINE"
+    band = "BAND"
+    #: tile requires GDAL 3.11+
+    tile = "TILE"
+
+
+# https://github.com/rasterio/rasterio/blob/2d79e5f3a00e919ecaa9573adba34a78274ce48c/rasterio/enums.py#L185-L189
+class MaskFlags(IntEnum):
+    all_valid = 1
+    per_dataset = 2
+    alpha = 4
+    nodata = 8
+
+
+# https://github.com/rasterio/rasterio/blob/2d79e5f3a00e919ecaa9573adba34a78274ce48c/rasterio/enums.py#L192-L200
+class PhotometricInterp(Enum):
+    black = "MINISBLACK"
+    white = "MINISWHITE"
+    rgb = "RGB"
+    cmyk = "CMYK"
+    ycbcr = "YCbCr"
+    cielab = "CIELAB"
+    icclab = "ICCLAB"
+    itulab = "ITULAB"