rasterix 0.1a4__py3-none-any.whl → 0.2.0__py3-none-any.whl

rasterix/__init__.py

@@ -1,3 +1,4 @@
+from .options import get_options, set_options
 from .raster_index import RasterIndex, assign_index
 
 
@@ -12,4 +13,4 @@ def _get_version():
 
 __version__ = _get_version()
 
-__all__ = ["RasterIndex", "assign_index"]
+__all__ = ["RasterIndex", "assign_index", "set_options", "get_options"]

rasterix/_version.py

@@ -1,7 +1,14 @@
 # file generated by setuptools-scm
 # don't change, don't track in version control
 
-__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
 
 TYPE_CHECKING = False
 if TYPE_CHECKING:
@@ -9,13 +16,19 @@ if TYPE_CHECKING:
     from typing import Union
 
     VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
 else:
     VERSION_TUPLE = object
+    COMMIT_ID = object
 
 version: str
 __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
 
-__version__ = version = '0.1a4'
-__version_tuple__ = version_tuple = (0, 1, 'a4')
+__version__ = version = '0.2.0'
+__version_tuple__ = version_tuple = (0, 2, 0)
+
+__commit_id__ = commit_id = None

rasterix/lib.py

@@ -0,0 +1,180 @@
+"""Shared library utilities for rasterix."""
+
+import logging
+from typing import NotRequired, TypedDict
+
+from affine import Affine
+
+# https://github.com/zarr-conventions/spatial
+_ZARR_SPATIAL_CONVENTION_UUID = "689b58e2-cf7b-45e0-9fff-9cfc0883d6b4"
+
+
+# Define TRACE level (lower than DEBUG)
+TRACE = 5
+logging.addLevelName(TRACE, "TRACE")
+
+
+class TraceLogger(logging.Logger):
+    """Logger with trace level support."""
+
+    def trace(self, message, *args, **kwargs):
+        """Log a message with severity 'TRACE'."""
+        if self.isEnabledFor(TRACE):
+            self._log(TRACE, message, args, **kwargs)
+
+
+# Set the custom logger class
+logging.setLoggerClass(TraceLogger)
+
+# Create logger for the rasterix package
+logger = logging.getLogger("rasterix")
+
+
+def affine_from_tiepoint_and_scale(
+    tiepoint: list[float] | tuple[float, ...],
+    scale: list[float] | tuple[float, ...],
+) -> Affine:
+    """Create an Affine transform from GeoTIFF tiepoint and pixel scale.
+
+    Parameters
+    ----------
+    tiepoint : list or tuple
+        GeoTIFF model tiepoint in format [I, J, K, X, Y, Z]
+        where (I, J, K) are pixel coords and (X, Y, Z) are world coords.
+    scale : list or tuple
+        GeoTIFF model pixel scale in format [ScaleX, ScaleY, ScaleZ].
+
+    Returns
+    -------
+    Affine
+        Affine transformation matrix.
+
+    Raises
+    ------
+    AssertionError
+        If ScaleZ is not 0 (only 2D rasters are supported).
+
+    Examples
+    --------
+    >>> tiepoint = [0.0, 0.0, 0.0, 323400.0, 4265400.0, 0.0]
+    >>> scale = [30.0, 30.0, 0.0]
+    >>> affine = affine_from_tiepoint_and_scale(tiepoint, scale)
+    """
+    if len(tiepoint) < 6:
+        raise ValueError(f"tiepoint must have at least 6 elements, got {len(tiepoint)}")
+    if len(scale) < 3:
+        raise ValueError(f"scale must have at least 3 elements, got {len(scale)}")
+
+    i, j, k, x, y, z = tiepoint[:6]
+    scale_x, scale_y, scale_z = scale[:3]
+
+    # We only support 2D rasters
+    assert scale_z == 0, f"Z pixel scale must be 0 for 2D rasters, got {scale_z}"
+
+    # The tiepoint gives us the world coordinates at pixel (I, J)
+    # Affine transform: x_world = c + i * a, y_world = f + j * e
+    # So: c = x - i * scale_x, f = y - j * scale_y
+    c = x - i * scale_x
+    f = y - j * scale_y
+
+    return Affine.translation(c, f) * Affine.scale(scale_x, scale_y)
+
+
+def affine_from_stac_proj_metadata(metadata: dict) -> Affine | None:
+    """Extract Affine transform from STAC projection metadata.
+
+    Parameters
+    ----------
+    metadata : dict
+        Dictionary containing STAC metadata. Should contain a 'proj:transform' key.
+
+    Returns
+    -------
+    Affine or None
+        Affine transformation matrix if 'proj:transform' is found, None otherwise.
+
+    Examples
+    --------
+    >>> metadata = {"proj:transform": [30.0, 0.0, 323400.0, 0.0, 30.0, 4268400.0]}
+    >>> affine = affine_from_stac_proj_metadata(metadata)
+    """
+    if "proj:transform" not in metadata:
+        return None
+
+    transform = metadata["proj:transform"]
+    # proj:transform is a 3x3 matrix in row-major order, but typically only 6 elements
+    # [a, b, c, d, e, f, 0, 0, 1] where the affine is constructed from first 6 elements
+    if len(transform) < 6:
+        raise ValueError(f"proj:transform must have at least 6 elements, got {len(transform)}")
+
+    a, b, c, d, e, f = transform[:6]
+    return Affine(a, b, c, d, e, f)
+
+
+_ZarrConventionRegistration = TypedDict("_ZarrConventionRegistration", {"spatial:": str})
+
+_ZarrSpatialMetadata = TypedDict(
+    "_ZarrSpatialMetadata",
+    {
+        "zarr_conventions": NotRequired[list[_ZarrConventionRegistration | dict]],
+        "spatial:transform": NotRequired[list[float]],
+        "spatial:transform_type": NotRequired[str],
+        "spatial:registration": NotRequired[str],
+    },
+)
+
+
+def _has_spatial_zarr_convention(metadata: _ZarrSpatialMetadata) -> bool:
+    zarr_conventions = metadata.get("zarr_conventions")
+    if not zarr_conventions:
+        return False
+    for entry in zarr_conventions:
+        if isinstance(entry, dict) and (
+            entry.get("uuid") == _ZARR_SPATIAL_CONVENTION_UUID or entry.get("name") == "spatial:"
+        ):
+            return True
+    return False
+
+
+def affine_from_spatial_zarr_convention(metadata: dict) -> Affine | None:
+    """Extract Affine transform from Zarr spatial convention metadata.
+
+    See https://github.com/zarr-conventions/spatial for the full specification.
+
+    Parameters
+    ----------
+    metadata : dict
+        Dictionary containing Zarr spatial convention metadata.
+
+    Returns
+    -------
+    Affine or None
+        Affine transformation matrix if minimal Zarr spatial metadata is found, None otherwise.
+
+    Examples
+    --------
+    >>> ds: xr.Dataset = ...
+    >>> affine = affine_from_spatial_zarr_convention(ds.attrs)
+    """
+    possibly_spatial_metadata: _ZarrSpatialMetadata = metadata  # type: ignore[assignment]
+
+    if _has_spatial_zarr_convention(possibly_spatial_metadata):
+        if transform := possibly_spatial_metadata.get("spatial:transform"):
+            if len(transform) < 6:
+                raise ValueError(f"spatial:transform must have at least 6 elements, got {len(transform)}")
+
+            transform_type = possibly_spatial_metadata.get("spatial:transform_type", "affine")
+            if transform_type != "affine":
+                raise NotImplementedError(
+                    f"Unsupported spatial:transform_type {transform_type!r}; only 'affine' is supported."
+                )
+
+            registration = possibly_spatial_metadata.get("spatial:registration", "pixel")
+            if registration != "pixel":
+                raise NotImplementedError(
+                    f"Unsupported spatial:registration {registration!r}; only 'pixel' is supported."
+                )
+
+            return Affine(*map(float, transform[:6]))
+
+    return None

rasterix/odc_compat.py

@@ -340,6 +340,29 @@ class BoundingBox(Sequence[float]):
     def __hash__(self) -> int:
         return hash(self._box)
 
+    def isclose(self, other: "BoundingBox", rtol: float = 1e-12, atol: float = 0.0) -> bool:
+        """
+        Check if two bounding boxes are approximately equal.
+
+        Parameters
+        ----------
+        other : BoundingBox
+            The bounding box to compare against.
+        rtol : float, default 1e-12
+            Relative tolerance for comparison.
+        atol : float, default 0.0
+            Absolute tolerance for comparison.
+
+        Returns
+        -------
+        bool
+            True if all four bounds (left, bottom, right, top) are close
+            within the specified tolerances.
+        """
+        if not isinstance(other, BoundingBox):
+            return False
+        return all(math.isclose(a, b, rel_tol=rtol, abs_tol=atol) for a, b in zip(self._box, other._box))
+
     def __len__(self) -> int:
         return 4
 

rasterix/options.py

@@ -0,0 +1,75 @@
+"""Options for rasterix with context manager support."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import Any
+
+OPTIONS: dict[str, Any] = {
+    "transform_rtol": 1e-12,
+    "transform_atol": 0.0,
+}
+
+
+def _validate_tolerance(value: Any) -> bool:
+    """Validate that value is a non-negative float."""
+    return isinstance(value, int | float) and value >= 0
+
+
+_VALIDATORS = {
+    "transform_rtol": _validate_tolerance,
+    "transform_atol": _validate_tolerance,
+}
+
+
+@contextmanager
+def set_options(**kwargs):
+    """
+    Set options for rasterix in a controlled context.
+
+    Parameters
+    ----------
+    transform_rtol : float, default: 1e-12
+        Relative tolerance for comparing affine transform parameters
+        during alignment and concatenation operations. This small default
+        handles typical floating-point representation noise.
+    transform_atol : float, default: 0.0
+        Absolute tolerance for comparing affine transform parameters.
+
+    Examples
+    --------
+    Use as a context manager:
+
+    >>> import rasterix
+    >>> import xarray as xr
+    >>> with rasterix.set_options(transform_rtol=1e-9):
+    ...     result = xr.concat([ds1, ds2], dim="x")
+    """
+    old = {}
+    for k, v in kwargs.items():
+        if k not in OPTIONS:
+            raise ValueError(f"argument name {k!r} is not in the set of valid options {set(OPTIONS)!r}")
+        if k in _VALIDATORS and not _VALIDATORS[k](v):
+            raise ValueError(f"option {k!r} given an invalid value: {v!r}. Expected a non-negative number.")
+        old[k] = OPTIONS[k]
+    OPTIONS.update(kwargs)
+    try:
+        yield
+    finally:
+        OPTIONS.update(old)
+
+
+def get_options() -> dict[str, Any]:
+    """
+    Get current options for rasterix.
+
+    Returns
+    -------
+    dict
+        Dictionary of current option values.
+
+    See Also
+    --------
+    set_options
+    """
+    return OPTIONS.copy()