rasterix 0.1.1__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

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.1.1'
-__version_tuple__ = version_tuple = (0, 1, 1)
+__version__ = version = '0.2.0'
+__version_tuple__ = version_tuple = (0, 2, 0)
 
 __commit_id__ = commit_id = None

rasterix/lib.py

@@ -1,9 +1,14 @@
 """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")
@@ -104,3 +109,72 @@ def affine_from_stac_proj_metadata(metadata: dict) -> Affine | None:
 
     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()

rasterix/raster_index.py

@@ -20,8 +20,9 @@ from xarray.core.types import JoinOptions
 from xproj.typing import CRSAwareIndex
 
 from rasterix.odc_compat import BoundingBox, bbox_intersection, bbox_union, maybe_int, snap_grid
+from rasterix.options import get_options as get_rasterix_options
 from rasterix.rioxarray_compat import guess_dims
-from rasterix.utils import get_affine
+from rasterix.utils import get_affine, get_crs_from_proj_zarr_convention
 
 T_Xarray = TypeVar("T_Xarray", "DataArray", "Dataset")
 
@@ -87,22 +88,34 @@ def assign_index(
 
     affine = get_affine(obj, x_dim=x_dim, y_dim=y_dim, clear_transform=True)
 
+    detected_crs = obj.proj.crs if crs else None
+    if detected_crs is None:
+        detected_crs = get_crs_from_proj_zarr_convention(obj)
+
     index = RasterIndex.from_transform(
         affine,
         width=obj.sizes[x_dim],
         height=obj.sizes[y_dim],
         x_dim=x_dim,
         y_dim=y_dim,
-        crs=obj.proj.crs if crs else None,
+        crs=detected_crs,
     )
     coords = Coordinates.from_xindex(index)
     return obj.assign_coords(coords)
 
 
+def _isclose(a: float, b: float) -> bool:
+    """Check if two floats are close using rasterix tolerance options."""
+    opts = get_rasterix_options()
+    return math.isclose(a, b, rel_tol=opts["transform_rtol"], abs_tol=opts["transform_atol"])
+
+
 def _assert_transforms_are_compatible(*affines) -> None:
     A1 = affines[0]
     for index, A2 in enumerate(affines[1:]):
-        if A1.a != A2.a or A1.b != A2.b or A1.d != A2.d or A1.e != A2.e:
+        if not (
+            _isclose(A1.a, A2.a) and _isclose(A1.b, A2.b) and _isclose(A1.d, A2.d) and _isclose(A1.e, A2.e)
+        ):
             raise ValueError(
                 f"Transform parameters are not compatible for affine 0: {A1}, and affine {index + 1} {A2}"
             )
@@ -219,9 +232,9 @@ class AxisAffineTransform(CoordinateTransform):
 
         # only compare the affine parameters of the relevant axis
         if self.is_xaxis:
-            affine_match = self.affine.a == other.affine.a and self.affine.c == other.affine.c
+            affine_match = _isclose(self.affine.a, other.affine.a) and _isclose(self.affine.c, other.affine.c)
         else:
-            affine_match = self.affine.e == other.affine.e and self.affine.f == other.affine.f
+            affine_match = _isclose(self.affine.e, other.affine.e) and _isclose(self.affine.f, other.affine.f)
 
         return affine_match and self.size == other.size
 
@@ -312,9 +325,12 @@ class AxisAffineTransformIndex(CoordinateTransformIndex):
         label = labels[coord_name]
         transform = self.axis_transform
         if isinstance(label, slice):
+            # Use 'is None' check instead of 'or' to correctly handle 0 values
             label = slice(
-                label.start or transform.forward({coord_name: 0})[coord_name],
-                label.stop or transform.forward({coord_name: transform.size})[coord_name],
+                transform.forward({coord_name: 0})[coord_name] if label.start is None else label.start,
+                transform.forward({coord_name: transform.size})[coord_name]
+                if label.stop is None
+                else label.stop,
                 label.step,
             )
             if label.step is None:
@@ -322,8 +338,12 @@ class AxisAffineTransformIndex(CoordinateTransformIndex):
                 pos = self.transform.reverse({coord_name: np.array([label.start, label.stop])})
                 # np.round rounds to even, this way we round upwards
                 pos = np.floor(pos[self.dim] + 0.5).astype("int")
-                new_start = max(pos[0], 0)
-                new_stop = min(pos[1] + 1, self.axis_transform.size)
+                size = self.axis_transform.size
+                # Clamp both start and stop to valid range [0, size]
+                new_start = max(min(pos[0], size), 0)
+                new_stop = max(min(pos[1] + 1, size), 0)
+                # Ensure stop >= start (empty slice if selection is completely outside bounds)
+                new_stop = max(new_stop, new_start)
                 return IndexSelResult({self.dim: slice(new_start, new_stop)})
             else:
                 # otherwise convert to basic (array) indexing
@@ -575,6 +595,89 @@ class RasterIndex(Index, xproj.ProjIndexMixin):
 
         return cls(index, crs=crs)
 
+    @classmethod
+    def from_geotransform(
+        cls,
+        geotransform: Sequence[float] | str,
+        *,
+        width: int,
+        height: int,
+        x_dim: str = "x",
+        y_dim: str = "y",
+        x_coord_name: str = "xc",
+        y_coord_name: str = "yc",
+        crs: CRS | Any | None = None,
+    ) -> RasterIndex:
+        """Create a RasterIndex from a GDAL-style GeoTransform.
+
+        Parameters
+        ----------
+        geotransform : sequence of float or str
+            GDAL GeoTransform as a 6-element sequence (c, a, b, f, d, e) or a
+            space-separated string of 6 numbers. The elements are:
+            - c: x-coordinate of the upper-left corner of the upper-left pixel
+            - a: pixel width (x-direction resolution)
+            - b: row rotation (typically 0)
+            - f: y-coordinate of the upper-left corner of the upper-left pixel
+            - d: column rotation (typically 0)
+            - e: pixel height (y-direction resolution, typically negative)
+        width : int
+            Number of pixels in the x direction.
+        height : int
+            Number of pixels in the y direction.
+        x_dim : str, optional
+            Name for the x dimension.
+        y_dim : str, optional
+            Name for the y dimension.
+        x_coord_name : str, optional
+            Name for the x coordinate. For non-rectilinear transforms only.
+        y_coord_name : str, optional
+            Name for the y coordinate. For non-rectilinear transforms only.
+        crs : :class:`pyproj.crs.CRS` or any, optional
+            The coordinate reference system. Any value accepted by
+            :meth:`pyproj.crs.CRS.from_user_input`.
+
+        Returns
+        -------
+        RasterIndex
+            A new RasterIndex object with appropriate internal structure.
+
+        See Also
+        --------
+        from_transform : Create from an Affine transform.
+        as_geotransform : Convert RasterIndex back to GeoTransform string.
+
+        References
+        ----------
+        - `GDAL GeoTransform tutorial <https://gdal.org/en/stable/tutorials/geotransforms_tut.html>`_
+
+        Examples
+        --------
+        Create from a sequence:
+
+        >>> geotransform = (323400.0, 30.0, 0.0, 4265400.0, 0.0, -30.0)
+        >>> index = RasterIndex.from_geotransform(geotransform, width=100, height=100)
+
+        Create from a string (as stored in netCDF attributes):
+
+        >>> geotransform = "323400.0 30.0 0.0 4265400.0 0.0 -30.0"
+        >>> index = RasterIndex.from_geotransform(geotransform, width=100, height=100)
+        """
+        if isinstance(geotransform, str):
+            geotransform = tuple(map(float, geotransform.split()))
+
+        affine = Affine.from_gdal(*geotransform)
+        return cls.from_transform(
+            affine,
+            width=width,
+            height=height,
+            x_dim=x_dim,
+            y_dim=y_dim,
+            x_coord_name=x_coord_name,
+            y_coord_name=y_coord_name,
+            crs=crs,
+        )
+
     @classmethod
     def from_tiepoint_and_scale(
         cls,
@@ -891,10 +994,16 @@ class RasterIndex(Index, xproj.ProjIndexMixin):
         new_affine, Nx, Ny = bbox_to_affine(bbox, rx=affine.a, ry=affine.e)
         # TODO: set xdim, ydim explicitly
         new_index = self.from_transform(new_affine, width=Nx, height=Ny)
-        assert new_index.bbox == bbox
+        opts = get_rasterix_options()
+        assert new_index.bbox.isclose(bbox, rtol=opts["transform_rtol"], atol=opts["transform_atol"])
         return new_index
 
     def join(self, other: RasterIndex, how: JoinOptions = "inner") -> RasterIndex:
+        """Join two RasterIndexes by computing the union or intersection of their bounding boxes.
+
+        Transform compatibility is checked using the tolerance configured via
+        :py:func:`rasterix.set_options` (``transform_rtol`` and ``transform_atol``).
+        """
         if not self._proj_crs_equals(cast(CRSAwareIndex, other), allow_none=True):
             raise ValueError(
                 "raster indexes on objects to align do not have the same CRS\n"
@@ -1006,24 +1115,24 @@ def as_compatible_bboxes(*indexes: RasterIndex, concat_dim: Hashable | None) ->
     off_y = tuple(t.f for t in transforms)
 
     if concat_dim is not None:
-        if all(o == off_x[0] for o in off_x[1:]) and all(o == off_y[0] for o in off_y[1:]):
+        if all(_isclose(o, off_x[0]) for o in off_x[1:]) and all(_isclose(o, off_y[0]) for o in off_y[1:]):
             raise ValueError("Attempting to concatenate arrays with same transform along X or Y.")
 
     # note: Xarray alignment already ensures that the indexes dimensions are compatible.
     x_dim, y_dim = indexes[0].xy_dims
 
     if concat_dim == x_dim:
-        if any(off_y[0] != o for o in off_y[1:]):
-            raise ValueError("offsets must be identical in X when concatenating along Y")
-        if any(a != b for a, b in zip(off_x, expected_off_x)):
+        if any(not _isclose(off_y[0], o) for o in off_y[1:]):
+            raise ValueError("offsets must be identical in Y when concatenating along X")
+        if any(not _isclose(a, b) for a, b in zip(off_x, expected_off_x)):
             raise ValueError(
                 f"X offsets are incompatible. Provided offsets {off_x}, expected offsets: {expected_off_x}"
             )
     elif concat_dim == y_dim:
-        if any(off_x[0] != o for o in off_x[1:]):
+        if any(not _isclose(off_x[0], o) for o in off_x[1:]):
             raise ValueError("offsets must be identical in X when concatenating along Y")
 
-        if any(a != b for a, b in zip(off_y, expected_off_y)):
+        if any(not _isclose(a, b) for a, b in zip(off_y, expected_off_y)):
             raise ValueError(
                 f"Y offsets are incompatible. Provided offsets {off_y}, expected offsets: {expected_off_y}"
             )

rasterix/rasterize/__init__.py

@@ -0,0 +1,4 @@
+# Rasterization API
+from .core import geometry_clip, geometry_mask, rasterize
+
+__all__ = ["rasterize", "geometry_mask", "geometry_clip"]