async-tiff 0.2.0__cp311-abi3-manylinux_2_24_aarch64.whl → 0.5.0b4__cp311-abi3-manylinux_2_24_aarch64.whl

async_tiff/__init__.py

@@ -1,9 +1,30 @@
-from typing import TYPE_CHECKING
-
-from ._async_tiff import *
-from ._async_tiff import ___version
-
-if TYPE_CHECKING:
-    from . import store
+from . import enums
+from ._async_tiff import (
+    TIFF,
+    Array,
+    Colormap,
+    DecoderRegistry,
+    GeoKeyDirectory,
+    ImageFileDirectory,
+    ThreadPool,
+    Tile,
+    ___version,  # noqa: F403 # pyright:ignore[reportAttributeAccessIssue]
+)
+from ._decoder_runtime import Decoder
+from ._input import ObspecInput
 
 __version__: str = ___version()
+
+__all__ = [
+    "enums",
+    "Array",
+    "Colormap",
+    "Decoder",
+    "DecoderRegistry",
+    "GeoKeyDirectory",
+    "ImageFileDirectory",
+    "ThreadPool",
+    "TIFF",
+    "ObspecInput",
+    "Tile",
+]

async_tiff/_array.pyi

@@ -0,0 +1,45 @@
+import sys
+
+if sys.version_info >= (3, 12):
+    from collections.abc import Buffer
+else:
+    from typing_extensions import Buffer
+
+class Array(Buffer):
+    """A 3D array that implements Python's buffer protocol.
+
+    This allows zero-copy interoperability with numpy via `np.asarray(arr)`.
+    The array is immutable and exposes a read-only buffer.
+
+    Example:
+
+    ```python
+    import numpy as np
+    from async_tiff import Array
+
+    # Create from raw bytes
+    data = bytes([1, 2, 3, 4, 5, 6])
+    arr = Array(data, shape=(1, 2, 3), format="<B")  # 1x2x3 uint8 array
+
+    # Convert to numpy (zero-copy view)
+    np_arr = np.asarray(arr)
+    assert np_arr.shape == (1, 2, 3)
+    assert np_arr.dtype == np.uint8
+    ```
+    """
+
+    # This is intended only for tests
+    # def __init__(
+    #     self, data: Buffer, shape: tuple[int, int, int], format: str
+    # ) -> None: ...
+    def __buffer__(self, flags: int) -> memoryview[int]: ...
+    @property
+    def shape(self) -> tuple[int, int, int]:
+        """The shape of the array.
+
+        The interpretation depends on the PlanarConfiguration:
+
+        - PlanarConfiguration=1 (chunky): (height, width, bands)
+        - PlanarConfiguration=2 (planar): (bands, height, width)
+        """
+        ...

async_tiff/_async_tiff.pyi

@@ -1,8 +1,19 @@
-from ._decoder import Decoder as Decoder
-from ._decoder import DecoderRegistry as DecoderRegistry
-from ._geo import GeoKeyDirectory as GeoKeyDirectory
-from ._ifd import ImageFileDirectory as ImageFileDirectory
-from ._thread_pool import ThreadPool as ThreadPool
-from ._tiff import ObspecInput as ObspecInput
-from ._tiff import TIFF as TIFF
-from ._tile import Tile as Tile
+from ._array import Array
+from ._colormap import Colormap
+from ._decoder import DecoderRegistry
+from ._geo import GeoKeyDirectory
+from ._ifd import ImageFileDirectory
+from ._thread_pool import ThreadPool
+from ._tiff import TIFF
+from ._tile import Tile
+
+__all__ = [
+    "Array",
+    "Colormap",
+    "DecoderRegistry",
+    "GeoKeyDirectory",
+    "ImageFileDirectory",
+    "ThreadPool",
+    "TIFF",
+    "Tile",
+]

async_tiff/_colormap.pyi

@@ -0,0 +1,14 @@
+import sys
+
+if sys.version_info >= (3, 12):
+    from collections.abc import Buffer
+else:
+    from typing_extensions import Buffer
+
+class Colormap(Buffer):
+    """A 1D array of u16 values representing a TIFF colormap.
+
+    Implements Python's buffer protocol for zero-copy access via `np.asarray()`.
+    """
+    def __buffer__(self, flags: int) -> memoryview[int]: ...
+    def __len__(self) -> int: ...

async_tiff/_decoder.pyi

@@ -1,20 +1,10 @@
-from typing import Protocol
-from collections.abc import Buffer
-
-from .enums import CompressionMethod
-
-class Decoder(Protocol):
-    """A custom Python-provided decompression algorithm."""
-    # In the future, we could pass in photometric interpretation and jpeg tables as
-    # well.
-    @staticmethod
-    def __call__(buffer: Buffer) -> Buffer:
-        """A callback to decode compressed data."""
+from ._decoder_runtime import Decoder
+from .enums import Compression
 
 class DecoderRegistry:
     """A registry holding multiple decoder methods."""
     def __init__(
-        self, custom_decoders: dict[CompressionMethod | int, Decoder] | None = None
+        self, custom_decoders: dict[Compression | int, Decoder] | None = None
     ) -> None:
         """Construct a new decoder registry.
 

async_tiff/_decoder_runtime.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING, Protocol
+
+if TYPE_CHECKING:
+    if sys.version_info >= (3, 12):
+        from collections.abc import Buffer
+    else:
+        from typing_extensions import Buffer
+
+
+class Decoder(Protocol):
+    """A custom Python-provided decompression algorithm."""
+
+    # In the future, we could pass in photometric interpretation and jpeg tables as
+    # well.
+    @staticmethod
+    def __call__(buffer: Buffer) -> Buffer:
+        """A callback to decode compressed data."""
+        ...

async_tiff/_geo.pyi

@@ -1,4 +1,15 @@
+from collections.abc import Iterable
+from typing import Any
+
 class GeoKeyDirectory:
+    def keys(self) -> list[str]:
+        """A list of string keys representing the GeoKey fields."""
+    def __eq__(self, value: object) -> bool: ...
+    def __iter__(self) -> Iterable[str]:
+        """An iterable of string keys representing the GeoKey fields."""
+    def __getitem__(self, key: str) -> Any:
+        """Access GeoKey fields by string key."""
+
     @property
     def model_type(self) -> int | None: ...
     @property

async_tiff/_ifd.pyi

@@ -1,16 +1,29 @@
+from collections.abc import Iterable, Sequence
+from typing import Any
+
+from ._colormap import Colormap
+from ._geo import GeoKeyDirectory
+from ._tile import Tile
 from .enums import (
-    CompressionMethod,
+    Compression,
     PhotometricInterpretation,
     PlanarConfiguration,
     Predictor,
     ResolutionUnit,
     SampleFormat,
 )
-from ._geo import GeoKeyDirectory
 
 Value = int | float | str | tuple[int, int] | list[Value]
 
 class ImageFileDirectory:
+    def keys(self) -> list[str]:
+        """A list of string keys representing the IFD fields."""
+    def __eq__(self, value: object) -> bool: ...
+    def __iter__(self) -> Iterable[str]:
+        """An iterable of string keys representing the IFD fields."""
+    def __getitem__(self, key: str) -> Any:
+        """Access IFD fields by string key."""
+
     @property
     def new_subfile_type(self) -> int | None: ...
     @property
@@ -24,11 +37,11 @@ class ImageFileDirectory:
     @property
     def bits_per_sample(self) -> list[int]: ...
     @property
-    def compression(self) -> CompressionMethod | int:
+    def compression(self) -> Compression | int:
         """Access the compression tag.
 
         An `int` will be returned if the compression is not one of the values in
-        `CompressionMethod`.
+        `Compression`.
         """
     @property
     def photometric_interpretation(self) -> PhotometricInterpretation: ...
@@ -104,4 +117,33 @@ class ImageFileDirectory:
     @property
     def model_tiepoint(self) -> list[float] | None: ...
     @property
+    def model_transformation(self) -> list[float] | None: ...
+    @property
+    def gdal_nodata(self) -> str | None: ...
+    @property
+    def gdal_metadata(self) -> str | None: ...
+    @property
     def other_tags(self) -> dict[int, Value]: ...
+    @property
+    def colormap(self) -> Colormap | None:
+        """The colormap for palette-color images."""
+        ...
+    async def fetch_tile(self, x: int, y: int) -> Tile:
+        """Fetch a single tile.
+
+        Args:
+            x: The column index within the ifd to read from.
+            y: The row index within the ifd to read from.
+
+        Returns:
+            Tile response.
+        """
+    async def fetch_tiles(self, xy: Sequence[tuple[int, int]]) -> list[Tile]:
+        """Fetch multiple tiles concurrently.
+
+        Args:
+            xy: The (column, row) indexes within the ifd to read from.
+
+        Returns:
+            Tile responses.
+        """

async_tiff/_input.py

@@ -0,0 +1,11 @@
+from typing import Protocol
+
+from obspec import GetRangeAsync, GetRangesAsync
+
+
+class ObspecInput(GetRangeAsync, GetRangesAsync, Protocol):
+    """Supported obspec input to reader.
+
+    Anything that implements [GetRangeAsync][obspec.GetRangeAsync] and
+    [GetRangesAsync][obspec.GetRangesAsync] can be used as an input to the TIFF reader.
+    """

async_tiff/_tiff.pyi

@@ -1,14 +1,11 @@
-from typing import Protocol
-from ._tile import Tile
+from typing import Sequence
+
 from ._ifd import ImageFileDirectory
+from ._input import ObspecInput
+from ._tile import Tile
+from .enums import Endianness
 from .store import ObjectStore
 
-# Fix exports
-from obspec._get import GetRangeAsync, GetRangesAsync
-
-class ObspecInput(GetRangeAsync, GetRangesAsync, Protocol):
-    """Supported obspec input to reader."""
-
 class TIFF:
     @classmethod
     async def open(
@@ -17,6 +14,7 @@ class TIFF:
         *,
         store: ObjectStore | ObspecInput,
         prefetch: int = 32768,
+        multiplier: int | float = 2.0,
     ) -> TIFF:
         """Open a new TIFF.
 
@@ -24,10 +22,29 @@ class TIFF:
             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.
         """
+
+    @property
+    def endianness(self) -> Endianness:
+        """The endianness of this TIFF file."""
+
+    def ifd(self, index: int) -> ImageFileDirectory:
+        """Access a specific IFD by index.
+
+        Args:
+            index: The IFD index to access.
+
+        Returns:
+            The requested IFD.
+        """
+
     @property
     def ifds(self) -> list[ImageFileDirectory]:
         """Access the underlying IFDs of this TIFF.
@@ -46,12 +63,11 @@ class TIFF:
         Returns:
             Tile response.
         """
-    async def fetch_tiles(self, x: list[int], y: list[int], z: int) -> list[Tile]:
+    async def fetch_tiles(self, xy: Sequence[tuple[int, int]], z: int) -> list[Tile]:
         """Fetch multiple tiles concurrently.
 
         Args:
-            x: The column indexes within the ifd to read from.
-            y: The row indexes within the ifd to read from.
+            xy: The (column, row) indexes within the ifd to read from.
             z: The IFD index to read from.
 
         Returns:

async_tiff/_tile.pyi

@@ -1,8 +1,9 @@
 from collections.abc import Buffer
 
-from .enums import CompressionMethod
+from ._array import Array
 from ._decoder import DecoderRegistry
 from ._thread_pool import ThreadPool
+from .enums import Compression
 
 class Tile:
     """A representation of a TIFF image tile."""
@@ -16,20 +17,42 @@ class Tile:
     def compressed_bytes(self) -> Buffer:
         """The compressed bytes underlying this tile."""
     @property
-    def compression_method(self) -> CompressionMethod | int:
+    def compression_method(self) -> Compression | int:
         """The compression method used by this tile."""
-    async def decode_async(
+    def decode_sync(
+        self,
+        *,
+        decoder_registry: DecoderRegistry | None = None,
+    ) -> Array:
+        """Decode this tile's data.
+
+        **Note**: This is a blocking function and will perform the tile decompression on
+        the current thread. Prefer using the asynchronous `decode` method, which will
+        offload decompression to a thread pool.
+
+        Keyword Args:
+            decoder_registry: the decoders to use for decompression. Defaults to None, in which case a default decoder registry is used.
+
+        Returns:
+            Decoded tile data as an Array instance.
+        """
+
+    async def decode(
         self,
         *,
         decoder_registry: DecoderRegistry | None = None,
         pool: ThreadPool | None = None,
-    ) -> Buffer:
+    ) -> Array:
         """Decode this tile's data.
 
+        This is an asynchronous function that will offload the tile decompression to a
+        thread pool.
+
         Keyword Args:
-            decoder_registry: the decoders to use for decompression. Defaults to None.
-            pool: the thread pool on which to run decompression. Defaults to None.
+            decoder_registry: the decoders to use for decompression. Defaults to None, in which case a default decoder registry is used.
+            pool: the thread pool on which to run decompression. Defaults to None, in
+                which case, a default thread pool is used.
 
         Returns:
-            Decoded tile data as a buffer.
+            Decoded tile data as an Array instance.
         """

async_tiff/enums.py

@@ -1,7 +1,7 @@
 from enum import IntEnum
 
 
-class CompressionMethod(IntEnum):
+class Compression(IntEnum):
     """
     See [TIFF compression
     tags](https://www.awaresystems.be/imaging/tiff/tifftags/compression.html) for
@@ -19,6 +19,15 @@ class CompressionMethod(IntEnum):
     Deflate = 8
     OldDeflate = 0x80B2
     PackBits = 0x8005
+    WebP = 50001
+    LZMA = 34925
+    JPEG2k = 34712
+    ZSTD = 0xC350
+
+
+class Endianness(IntEnum):
+    LittleEndian = 0
+    BigEndian = 1
 
 
 class PhotometricInterpretation(IntEnum):
@@ -52,5 +61,5 @@ class ResolutionUnit(IntEnum):
 class SampleFormat(IntEnum):
     Uint = 1
     Int = 2
-    IEEEFP = 3
+    Float = 3
     Void = 4

async_tiff-0.5.0b4.dist-info/METADATA

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: async-tiff
+Version: 0.5.0b4
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Dist: obspec>=0.1.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+
+# async-tiff
+
+[![PyPI][pypi_badge]][pypi_link]
+
+[pypi_badge]: https://badge.fury.io/py/async-tiff.svg
+[pypi_link]: https://pypi.org/project/async-tiff/
+
+Fast, low-level async TIFF reader for Python.
+
+This documentation is for the Python bindings. [Refer here for the Rust crate documentation](https://docs.rs/async-tiff).
+
+For a higher-level API to read GeoTIFF files, visit [`async-geotiff`][async-geotiff].
+
+[async-geotiff]: https://developmentseed.org/async-geotiff
+
+## Examples
+
+### Reading NAIP
+
+```py
+from async_tiff import TIFF
+from async_tiff.store import S3Store
+
+# You'll also need to provide credentials to access a requester pays bucket
+store = S3Store("naip-visualization", region="us-west-2", request_payer=True)
+path = "ny/2022/60cm/rgb/40073/m_4007307_sw_18_060_20220803.tif"
+
+tiff = await TIFF.open(path, store=store)
+primary_ifd = tiff.ifds[0]
+
+primary_ifd.geo_key_directory.citation
+# 'NAD83 / UTM zone 18N'
+
+primary_ifd.geo_key_directory.projected_type
+# 26918
+# (EPSG code)
+
+primary_ifd.sample_format
+# [<SampleFormat.Uint: 1>, <SampleFormat.Uint: 1>, <SampleFormat.Uint: 1>]
+
+primary_ifd.bits_per_sample
+# [8, 8, 8]
+
+tile = await tiff.fetch_tile(0, 0, 4)
+array = await tile.decode()
+
+# Use rasterio and matplotlib for visualization
+import numpy as np
+from rasterio.plot import reshape_as_raster, show
+
+# Zero-copy conversion of the rust array into a numpy array
+np_array = np.asarray(array)
+
+# Then we need to reshape the "image" axes into "raster" axes
+# https://rasterio.readthedocs.io/en/stable/topics/image_processing.html
+show(reshape_as_raster(np_array), adjust=True)
+```
+
+![](assets/naip-example.jpg)
+
+
+### Reading Sentinel 2 L2A
+
+```py
+import numpy as np
+from async_tiff import TIFF
+from async_tiff.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/B04.tif"
+
+tiff = await TIFF.open(path, store=store)
+primary_ifd = tiff.ifds[0]
+# Text readable citation
+primary_ifd.geo_key_directory.citation
+# EPSG code
+primary_ifd.geo_key_directory.projected_type
+
+primary_ifd.sample_format[0]
+# <SampleFormat.Uint: 1>
+primary_ifd.bits_per_sample[0]
+# 16
+
+tile = await tiff.fetch_tile(0, 0, 0)
+array = await tile.decode()
+
+# Zero-copy conversion of the rust array into a numpy array
+np_array = np.asarray(array)
+np_array.shape
+# (1024, 1024, 1)
+```
+
+

async_tiff-0.5.0b4.dist-info/RECORD

@@ -0,0 +1,18 @@
+async_tiff/__init__.py,sha256=gdLgfl7BLntXTceX9JdojgOwy_8sH7-YuEuQedBr3o4,559
+async_tiff/_array.pyi,sha256=muitV2BmObMPBF1O1mgo9a89posx7-ubsl4XftG5WO4,1257
+async_tiff/_async_tiff.abi3.so,sha256=kV_PmXYmjUs867NmvGpURu-NKHL3yL5QEkCtgv28280,8769336
+async_tiff/_async_tiff.pyi,sha256=I0Z9ey5GYZYfjJB4ZEyPUzHTsw0GcA5KBrAbTiThMc8,410
+async_tiff/_colormap.pyi,sha256=NrXLqUq3U81bI0zG8OLgQwv_JM0YS-MrVgx-1nD6j3g,402
+async_tiff/_decoder.pyi,sha256=tRHzZbZj1V6lDireFpNQ-f2h2tPFqh2ExYu4L6v0Cqc,709
+async_tiff/_decoder_runtime.py,sha256=N2IC7XTgC1TmGmB7ZXCJbrVVSbn6G85cWgJ6k87XpT8,553
+async_tiff/_geo.pyi,sha256=h71Y9zZ5vYxXaXAR4QAYmBJ0FOhLfXMMJA85p474eTE,3451
+async_tiff/_ifd.pyi,sha256=zjU_fENQr8roZMyTFRJpClLzOpHJHHeNhO--iN0XwMA,4698
+async_tiff/_input.py,sha256=CXgxr2kCxmKWQ3Ev3Jud6N5R1Vpl1r4YXpnr7485c8U,349
+async_tiff/_thread_pool.pyi,sha256=fbDu9kbo8RNlq7bBBxuuu_6ub20L5cAfXBM-J7Y0PC8,181
+async_tiff/_tiff.pyi,sha256=-TSMH4-k6moaDE1zoXPDkzGF1xLfd_1DzYMzAcALVu0,2178
+async_tiff/_tile.pyi,sha256=NBUciMH6nan6qQLt30p9msUiY4BKh4ZmW4r9CsqtYho,1961
+async_tiff/enums.py,sha256=81S3s7eKtCgxuLxuI2pw5K_43S7I3wJ8m7LRpKAzj_I,1047
+async_tiff/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+async_tiff-0.5.0b4.dist-info/METADATA,sha256=HP-ILZqvAvK-1GAhkTTnzw1Qyq17dZfdJ1-lgpYiX8Q,2741
+async_tiff-0.5.0b4.dist-info/WHEEL,sha256=tHTmiwnSeAz6X17kgYgRMkULH4bS61-tufZJfjnOFww,109
+async_tiff-0.5.0b4.dist-info/RECORD,,

{async_tiff-0.2.0.dist-info → async_tiff-0.5.0b4.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: maturin (1.9.6)
+Generator: maturin (1.11.5)
 Root-Is-Purelib: false
 Tag: cp311-abi3-manylinux_2_24_aarch64

async_tiff-0.2.0.dist-info/METADATA

@@ -1,8 +0,0 @@
-Metadata-Version: 2.4
-Name: async-tiff
-Version: 0.2.0
-Classifier: Programming Language :: Rust
-Classifier: Programming Language :: Python :: Implementation :: CPython
-Classifier: Programming Language :: Python :: Implementation :: PyPy
-Requires-Dist: obspec>=0.1.0b3
-Requires-Python: >=3.10

async_tiff-0.2.0.dist-info/RECORD

@@ -1,14 +0,0 @@
-async_tiff-0.2.0.dist-info/METADATA,sha256=MTZP5SVb2oiRdJSDFuOFo_K-kvggjtocqAV0dIh8P94,291
-async_tiff-0.2.0.dist-info/WHEEL,sha256=MMYhddnSlygFICZWut0h6-wgR7QpIP6ZqzmhW1DJt4w,108
-async_tiff/__init__.py,sha256=KTVCBLwRsYMz1f4fe0uVpKPhfymTMGNXe4WKxrqtjcQ,173
-async_tiff/_async_tiff.abi3.so,sha256=_OX5jnwQ3hw9K1PN64a92kYOCbqab7cfyAwOi2IxxRs,8017272
-async_tiff/_async_tiff.pyi,sha256=FBpM_a-AvnhF-eA5_zpKDSLWbh4lEFBTz8FxxzpJBrU,371
-async_tiff/_decoder.pyi,sha256=GezYsb_FpLOG8d7JN4FO3aC_itMwigBr6cF8qzg05M8,1043
-async_tiff/_geo.pyi,sha256=AXmfvki0b04OnECD63PKkcPcxyHudbDRKQVZOCx6K7g,3031
-async_tiff/_ifd.pyi,sha256=61WU6zvY8uxePTc4b2IK_zhRwr4fj3Cc5LpBdRO1QR4,3374
-async_tiff/_thread_pool.pyi,sha256=fbDu9kbo8RNlq7bBBxuuu_6ub20L5cAfXBM-J7Y0PC8,181
-async_tiff/_tiff.pyi,sha256=rCt3O3TYeMTI9-ydO1eepO7UNV1rsDrg1MmDMdVoFu4,1689
-async_tiff/_tile.pyi,sha256=GzmAw-ysBx_s0JuQsY0AmF7UFDK_NIUMv3xubCATt2U,1102
-async_tiff/enums.py,sha256=y6kPfRJX9I7J8AwBBuO0mFI3uWfMSY6hmKEGRXbpDSI,915
-async_tiff/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-async_tiff-0.2.0.dist-info/RECORD,,