rastr 0.1.0__py3-none-any.whl

rastr/_version.py

@@ -0,0 +1,21 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)

rastr/arr/fill.py

@@ -0,0 +1,24 @@
+import numpy as np
+from numpy.typing import NDArray
+from scipy.interpolate import NearestNDInterpolator
+
+
+def fillna_nearest_neighbours(arr: NDArray[np.float64]) -> NDArray[np.float64]:
+    """Fill NaN values in an N-dimensional array with their nearest neighbours' values.
+
+    The nearest neighbour is determined using the Euclidean distance between array
+    indices, so there is equal weighting given in all directions (i.e. across all axes).
+    In the case of tiebreaks, the value from the neighbour with the lowest index is
+    imputed.
+    """
+    nonnan_mask = np.nonzero(~np.isnan(arr))
+    nonnan_idxs = np.array(nonnan_mask).transpose()
+
+    if nonnan_idxs.size == 0:
+        # Everything is NaN
+        return arr
+
+    # Interpolate at the array indices
+    interp = NearestNDInterpolator(nonnan_idxs, arr[nonnan_mask])
+    filled_arr = interp(*np.indices(arr.shape))
+    return filled_arr

rastr/create.py

@@ -0,0 +1,261 @@
+from collections.abc import Iterable
+from functools import partial
+
+import geopandas as gpd
+import numpy as np
+import pandas as pd
+import rasterio.features
+from affine import Affine
+from shapely.geometry import Point, Polygon
+from tqdm.notebook import tqdm
+
+from rastr.gis.fishnet import create_point_grid, get_point_grid_shape
+from rastr.meta import RasterMeta
+from rastr.raster import RasterModel
+
+
+class MissingColumnsError(ValueError):
+    """Raised when target columns are missing from the GeoDataFrame."""
+
+
+class NonNumericColumnsError(ValueError):
+    """Raised when target columns contain non-numeric data."""
+
+
+class RasterizationError(ValueError):
+    """Base exception for rasterization errors."""
+
+
+class OverlappingGeometriesError(RasterizationError):
+    """Raised when geometries overlap, which could lead to data loss."""
+
+
+def raster_distance_from_polygon(
+    polygon: Polygon,
+    *,
+    raster_meta: RasterMeta,
+    extent_polygon: Polygon | None = None,
+    snap_raster: RasterModel | None = None,
+    show_pbar: bool = False,
+) -> RasterModel:
+    """Make a raster where each cell's value is its centre's distance to a polygon.
+
+    The raster should use a projected coordinate system.
+
+    Parameters:
+        polygon: Polygon to measure distances to.
+        raster_meta: Raster configuration (giving cell_size, CRS, etc.).
+        extent_polygon: Polygon for raster cell extent; The bounding box of this
+                        polygon is the bounding box of the output raster. Cells outside
+                        this polygon but within the bounding box will be NaN-valued, and
+                        cells will not be generated centred outside the bounding box of
+                        this polygon.
+        snap_raster: An alternative to using the extent_polygon. If provided, the raster
+                     must have the exact same cell alignment as the snap_raster.
+        show_pbar: Whether to show a progress bar during the distance calculation.
+
+    Returns:
+        Array storing the distance between cell centres and the polygon. Cell are
+        NaN-valued if they are within the polygon or outside the extent polygon.
+
+    Raises:
+        ValueError: If the provided CRS is geographic (lat/lon).
+    """
+    if extent_polygon is None and snap_raster is None:
+        err_msg = "Either 'extent_polygon' or 'snap_raster' must be provided. "
+        raise ValueError(err_msg)
+    elif extent_polygon is not None and snap_raster is not None:
+        err_msg = "Only one of 'extent_polygon' or 'snap_raster' can be provided. "
+        raise ValueError(err_msg)
+
+    if not show_pbar:
+
+        def _pbar(x: Iterable) -> None:
+            return x  # No-op if no progress bar is needed
+
+    # Check if the provided CRS is projected (cartesian)
+    if raster_meta.crs.is_geographic:
+        err_msg = (
+            "The provided CRS is geographic (lat/lon). Please use a projected CRS."
+        )
+        raise ValueError(err_msg)
+
+    # Calculate the coordinates
+    if snap_raster is not None:
+        x, y = snap_raster.get_xy()
+    else:
+        x, y = create_point_grid(
+            bounds=extent_polygon.bounds, cell_size=raster_meta.cell_size
+        )
+
+    points = [Point(x, y) for x, y in zip(x.flatten(), y.flatten(), strict=True)]
+
+    # Create a mask to identify points for which distance should be calculated
+    if extent_polygon is not None:
+        distance_extent = extent_polygon.difference(polygon)
+    else:
+        distance_extent = snap_raster.bbox.difference(polygon)
+
+    if show_pbar:
+        _pbar = partial(tqdm, desc="Finding points within extent")
+    mask = [distance_extent.intersects(point) for point in _pbar(points)]
+
+    if show_pbar:
+        _pbar = partial(tqdm, desc="Calculating distances")
+    distances = np.where(
+        mask, np.array([polygon.distance(point) for point in _pbar(points)]), np.nan
+    )
+    distance_raster = distances.reshape(x.shape)
+
+    return RasterModel(arr=distance_raster, raster_meta=raster_meta)
+
+
+def full_raster(
+    raster_meta: RasterMeta,
+    *,
+    bounds: tuple[float, float, float, float],
+    fill_value: float = np.nan,
+) -> RasterModel:
+    """Create a raster with a specified fill value for all cells."""
+    shape = get_point_grid_shape(bounds=bounds, cell_size=raster_meta.cell_size)
+    arr = np.full(shape, fill_value, dtype=np.float32)
+    return RasterModel(arr=arr, raster_meta=raster_meta)
+
+
+def rasterize_gdf(
+    gdf: gpd.GeoDataFrame,
+    *,
+    raster_meta: RasterMeta,
+    target_cols: list[str],
+) -> list[RasterModel]:
+    """Rasterize geometries from a GeoDataFrame.
+
+    Supports polygons, points, linestrings, and other geometry types.
+    Gaps will be set as NaN.
+
+    Args:
+        gdf: The geometries to rasterize (polygons, points, linestrings, etc.).
+        raster_meta: Metadata for the created rasters.
+        target_cols: A list of columns from the GeoDataFrame containing numeric
+                     datatypes. Each column will correspond to a separate raster
+                     in the output.
+
+    Returns:
+        Rasters for each column in `target_cols`.
+
+    Raises:
+        MissingColumnsError: If any of the target columns are not found in the
+                             GeoDataFrame.
+        NonNumericColumnsError: If any of the target columns contain non-numeric data.
+        OverlappingGeometriesError: If any geometries overlap, which could lead to
+                                    data loss in the rasterization process.
+    """
+    # Validate inputs using helper functions
+    _validate_columns_exist(gdf, target_cols)
+    _validate_columns_numeric(gdf, target_cols)
+    _validate_no_overlapping_geometries(gdf)
+
+    # Get the bounds from the GeoDataFrame and expand them to include potential gaps
+    bounds = gdf.total_bounds
+    min_x, min_y, max_x, max_y = bounds
+    cell_size = raster_meta.cell_size
+
+    # Expand bounds by at least one cell size to ensure there are potential gaps
+    buffer = cell_size
+    expanded_bounds = (min_x - buffer, min_y - buffer, max_x + buffer, max_y + buffer)
+
+    # Create point grid to get raster dimensions and transform
+    shape = get_point_grid_shape(bounds=expanded_bounds, cell_size=cell_size)
+
+    # Create the affine transform for rasterization
+    transform = Affine.translation(
+        expanded_bounds[0], expanded_bounds[3]
+    ) * Affine.scale(cell_size, -cell_size)
+
+    # Create rasters for each target column using rasterio.features.rasterize
+    rasters = []
+    for col in target_cols:
+        # Create (geometry, value) pairs for rasterization
+        shapes = [
+            (geom, value) for geom, value in zip(gdf.geometry, gdf[col], strict=True)
+        ]
+
+        # Rasterize the geometries with their values
+        raster_array = rasterio.features.rasterize(
+            shapes,
+            out_shape=shape,
+            transform=transform,
+            fill=np.nan,  # Fill gaps with NaN
+            dtype=np.float32,
+        )
+
+        # Create RasterModel
+        raster = RasterModel(arr=raster_array, raster_meta=raster_meta)
+        rasters.append(raster)
+
+    return rasters
+
+
+def _validate_columns_exist(gdf: gpd.GeoDataFrame, target_cols: list[str]) -> None:
+    """Validate that all target columns exist in the GeoDataFrame.
+
+    Args:
+        gdf: The GeoDataFrame to check.
+        target_cols: List of column names to validate.
+
+    Raises:
+        MissingColumnsError: If any columns are missing.
+    """
+    missing_cols = [col for col in target_cols if col not in gdf.columns]
+    if missing_cols:
+        msg = f"Target columns not found in GeoDataFrame: {missing_cols}"
+        raise MissingColumnsError(msg)
+
+
+def _validate_columns_numeric(gdf: gpd.GeoDataFrame, target_cols: list[str]) -> None:
+    """Validate that all target columns contain numeric data.
+
+    Args:
+        gdf: The GeoDataFrame to check.
+        target_cols: List of column names to validate.
+
+    Raises:
+        NonNumericColumnsError: If any columns contain non-numeric data.
+    """
+    non_numeric_cols = []
+    for col in target_cols:
+        if not pd.api.types.is_numeric_dtype(gdf[col]):
+            non_numeric_cols.append(col)
+    if non_numeric_cols:
+        msg = f"Target columns must contain numeric data: {non_numeric_cols}"
+        raise NonNumericColumnsError(msg)
+
+
+def _validate_no_overlapping_geometries(gdf: gpd.GeoDataFrame) -> None:
+    """Validate that geometries do not overlap.
+
+    Args:
+        gdf: The GeoDataFrame to check for overlapping geometries.
+
+    Raises:
+        OverlappingGeometriesError: If any geometries overlap.
+    """
+    # Check for overlaps by testing each geometry against all others
+    geometries = gdf.geometry.to_numpy()
+
+    for i in range(len(geometries)):
+        for j in range(i + 1, len(geometries)):
+            geom_i = geometries[i]
+            geom_j = geometries[j]
+
+            # Skip invalid geometries
+            if not geom_i.is_valid or not geom_j.is_valid:
+                continue
+
+            # Check if geometries overlap (not just touch)
+            if geom_i.overlaps(geom_j):
+                msg = (
+                    f"Overlapping geometries detected at indices {i} and {j}. "
+                    "Overlapping geometries can lead to data loss during rasterization."
+                )
+                raise OverlappingGeometriesError(msg)

rastr/gis/fishnet.py

@@ -0,0 +1,72 @@
+import geopandas as gpd
+import numpy as np
+from geopandas.array import GeometryArray
+from shapely import BufferCapStyle, BufferJoinStyle
+
+
+def create_point_grid(
+    *, bounds: tuple[float, float, float, float], cell_size: float
+) -> tuple[np.ndarray, np.ndarray]:
+    """Create a regular grid of point coordinates for raster centers.
+
+    This function replicates the original grid generation logic that uses
+    np.arange to ensure compatibility with existing code.
+
+    Args:
+        bounds: (xmin, ymin, xmax, ymax) bounding box.
+        cell_size: Size of each grid cell.
+
+    Returns:
+        Tuple of (x_coords, y_coords) meshgrids for raster cell centers.
+    """
+    xmin, ymin, xmax, ymax = bounds
+
+    # Use the original logic with np.arange for exact compatibility
+    x_coords = np.arange(xmin + cell_size / 2, xmax + cell_size / 2, cell_size)
+    y_coords = np.arange(ymax - cell_size / 2, ymin - cell_size / 2, -cell_size)
+
+    return np.meshgrid(x_coords, y_coords)
+
+
+def get_point_grid_shape(
+    *, bounds: tuple[float, float, float, float], cell_size: float
+) -> tuple[int, int]:
+    """Calculate the shape of the point grid based on bounds and cell size."""
+
+    xmin, ymin, xmax, ymax = bounds
+    ncols = int(np.ceil((xmax - xmin) / cell_size))
+    nrows = int(np.ceil((ymax - ymin) / cell_size))
+
+    return nrows, ncols
+
+
+def create_fishnet(
+    *, bounds: tuple[float, float, float, float], res: float
+) -> GeometryArray:
+    """Generate a fishnet of polygons from bounds.
+
+    The function generates a grid of polygons within the specified bounds, where each
+    cell has dimensions defined by `res`. If the resolution does not perfectly divide
+    the bounds' dimensions (i.e., if `res` is not a factor of (xmax - xmin) or
+    (ymax - ymin)), the grid is still generated such that it fully covers the bounds.
+    This can result in cells that extend beyond the specified bounds.
+
+    Args:
+        bounds: (xmin, ymin, xmax, ymax)
+        res: resolution (cell size)
+
+    Returns:
+        Shapely Polygons.
+    """
+    # Use the shared helper function to create the point grid
+    xx, yy = create_point_grid(bounds=bounds, cell_size=res)
+
+    # Create points from the grid coordinates
+    points = gpd.points_from_xy(xx.ravel(), yy.ravel())
+
+    # Buffer the points to create square polygons
+    polygons = points.buffer(
+        res / 2, cap_style=BufferCapStyle.square, join_style=BufferJoinStyle.mitre
+    )
+
+    return polygons

rastr/gis/smooth.py

@@ -0,0 +1,139 @@
+"""Utilities for smoothing geometries.
+
+Fork + Port of <https://github.com/philipschall/shapelysmooth> (Public domain)
+"""
+
+from __future__ import annotations
+
+from typing import TypeAlias
+
+import numpy as np
+from shapely.geometry import LineString, Polygon
+from typing_extensions import assert_never
+
+T: TypeAlias = LineString | Polygon
+
+
+class InputeTypeError(TypeError):
+    """Raised when the input geometry is of the incorrect type."""
+
+
+def catmull_rom_smooth(geometry: T, alpha: float = 0.5, subdivs: int = 10) -> T:
+    """Polyline smoothing using Catmull-Rom splines.
+
+    Args:
+        geometry: The geometry to smooth
+        alpha: The tension parameter, between 0 and 1 inclusive. Defaults to 0.5.
+               - For uniform Catmull-Rom splines, alpha = 0.
+               - For centripetal Catmull-Rom splines, alpha = 0.5.
+               - For chordal Catmull-Rom splines, alpha = 1.0.
+        subdivs:
+            Number of subdivisions of each polyline segment. Default value: 10.
+
+    Returns: The smoothed geometry.
+    """
+    coords, interior_coords = _get_coords(geometry)
+    coords_smoothed = _catmull_rom(coords, alpha=alpha, subdivs=subdivs)
+    if isinstance(geometry, LineString):
+        return type(geometry)(coords_smoothed)
+    elif isinstance(geometry, Polygon):
+        interior_coords_smoothed = [
+            _catmull_rom(c, alpha=alpha, subdivs=subdivs) for c in interior_coords
+        ]
+        return type(geometry)(coords_smoothed, holes=interior_coords_smoothed)
+    else:
+        assert_never(geometry)
+
+
+def _catmull_rom(
+    coords: np.ndarray,
+    *,
+    alpha: float = 0.5,
+    subdivs: int = 8,
+) -> list[tuple[float, float]]:
+    arr = np.asarray(coords, dtype=float)
+    if arr.shape[0] < 2:
+        return arr.tolist()
+
+    is_closed = np.allclose(arr[0], arr[-1])
+    if is_closed:
+        arr = np.vstack([arr[-2], arr, arr[2]])
+    else:
+        arr = np.vstack(
+            [
+                2.0 * arr[0] + 1.0 * arr[1],
+                arr,
+                2.0 * arr[-1] + 0.0 * arr[-2],
+            ]
+        )
+
+    new_ls = [tuple(arr[1])]
+    for k in range(len(arr) - 3):
+        slice4 = arr[k : k + 4]
+        tangents = [0.0]
+        for j in range(3):
+            dist = float(np.linalg.norm(slice4[j + 1] - slice4[j]))
+            tangents.append(float(tangents[-1] + dist**alpha))
+
+        # Resample: subdivs-1 samples strictly between t1 and t2
+        seg_len = (tangents[2] - tangents[1]) / float(subdivs)
+        if subdivs > 1:
+            ts = np.linspace(tangents[1] + seg_len, tangents[2] - seg_len, subdivs - 1)
+        else:
+            ts = np.array([])
+
+        interpolants = _recursive_eval(slice4, tangents, ts)
+        new_ls.extend(interpolants)
+        new_ls.append(tuple(slice4[2]))
+    return new_ls
+
+
+def _recursive_eval(
+    slice4: np.ndarray, tangents: list[float], ts: np.ndarray
+) -> list[tuple[float, float]]:
+    """De Boor/De Casteljau-style recursive linear interpolation over 4 control points.
+
+    Parameterized by the non-uniform 'tangents' values.
+    """
+    # N.B. comments are LLM-generated
+
+    out = []
+    for tp in ts:
+        # Start with the 4 control points for this segment
+        points = slice4.copy()
+        # Perform 3 levels of linear interpolation (De Casteljau's algorithm)
+        for r in range(1, 4):
+            idx = max(r - 2, 0)
+            new_points = []
+            # Interpolate between points at this level
+            for i in range(4 - r):
+                # Compute denominator for parameterization
+                denom = tangents[i + r - idx] - tangents[i + idx]
+                if denom == 0:
+                    # If degenerate (coincident tangents), use midpoint
+                    left_w = right_w = 0.5
+                else:
+                    # Otherwise, compute weights for linear interpolation
+                    left_w = (tangents[i + r - idx] - tp) / denom
+                    right_w = (tp - tangents[i + idx]) / denom
+                # Weighted average of the two points
+                pt = left_w * points[i] + right_w * points[i + 1]
+                new_points.append(pt)
+            # Move to the next level with the new set of points
+            points = np.array(new_points)
+        # The final point is the interpolated value for this parameter tp
+        out.append(tuple(points[0]))
+    return out
+
+
+def _get_coords(
+    geometry: LineString | Polygon,
+) -> tuple[np.ndarray, list[np.ndarray]]:
+    if isinstance(geometry, LineString):
+        return np.array(geometry.coords), []
+    elif isinstance(geometry, Polygon):
+        return np.array(geometry.exterior.coords), [
+            np.array(hole.coords) for hole in geometry.interiors
+        ]
+    else:
+        assert_never(geometry)

rastr/io.py

@@ -0,0 +1,29 @@
+from pathlib import Path
+
+import numpy as np
+import rasterio
+from numpy.typing import NDArray
+from pyproj.crs import CRS
+
+from rastr.meta import RasterMeta
+from rastr.raster import RasterModel
+
+
+def read_raster_inmem(raster_path: Path, crs: CRS | None = None) -> RasterModel:
+    """Read raster data from a file and return an in-memory Raster object."""
+    with rasterio.open(raster_path, mode="r") as dst:
+        # Read the entire array
+        arr: NDArray[np.float64] = dst.read()
+        arr = arr.squeeze().astype(np.float64)
+        # Extract metadata
+        cell_size = dst.res[0]
+        if crs is None:
+            crs = CRS.from_user_input(dst.crs)
+        transform = dst.transform
+        nodata = dst.nodata
+        if nodata is not None:
+            arr[arr == nodata] = np.nan
+
+    raster_meta = RasterMeta(cell_size=cell_size, crs=crs, transform=transform)
+    raster_obj = RasterModel(arr=arr, raster_meta=raster_meta)
+    return raster_obj

rastr/meta.py

@@ -0,0 +1,48 @@
+import numpy as np
+from affine import Affine
+from pydantic import BaseModel, InstanceOf
+from pyproj import CRS
+from typing_extensions import Self
+
+
+class RasterMeta(BaseModel, extra="forbid"):
+    """Raster metadata.
+
+    Attributes:
+        cell_size: Cell size in meters.
+        crs: Coordinate reference system.
+    """
+
+    cell_size: float
+    crs: InstanceOf[CRS]
+    transform: InstanceOf[Affine]
+
+    @classmethod
+    def example(cls) -> Self:
+        """Create an example RasterMeta object."""
+        return cls(
+            cell_size=2.0,
+            crs=CRS.from_epsg(2193),
+            transform=Affine.scale(2.0, 2.0),
+        )
+
+    def get_cell_centre_coords(self, shape: tuple[int, int]) -> np.ndarray:
+        """Return an array of (x, y) coordinates for the center of each cell.
+
+        The coordinates will be in the coordinate system defined by the
+        raster's transform.
+
+        Args:
+            shape: (rows, cols) of the raster array.
+
+        Returns:
+            np.ndarray of shape (rows, cols, 2) with (x, y) coordinates for each
+            cell center.
+        """
+        rows, cols = shape
+        x_idx = np.arange(cols)
+        y_idx = np.arange(rows)
+        xv, yv = np.meshgrid(x_idx, y_idx)
+        x_coords, y_coords = self.transform * (xv + 0.5, yv + 0.5)
+        coords = np.stack([x_coords, y_coords], axis=-1)
+        return coords

rastr/raster.py

@@ -0,0 +1,654 @@
+"""Raster data structure."""
+
+from collections.abc import Callable, Generator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import TYPE_CHECKING, Literal
+
+import geopandas as gpd
+import matplotlib as mpl
+import numpy as np
+import pandas as pd
+import rasterio.plot
+import rasterio.sample
+import rasterio.transform
+import skimage.measure
+import xyzservices.providers as xyz
+from matplotlib import pyplot as plt
+from matplotlib.axes import Axes
+from mpl_toolkits.axes_grid1 import make_axes_locatable
+from numpy.typing import NDArray
+from pydantic import BaseModel, InstanceOf, field_validator
+from pyproj.crs.crs import CRS
+from rasterio.enums import Resampling
+from rasterio.io import BufferedDatasetWriter, DatasetReader, DatasetWriter, MemoryFile
+from scipy.ndimage import gaussian_filter
+from shapely.geometry import LineString, Polygon
+from typing_extensions import Self
+
+from rastr.arr.fill import fillna_nearest_neighbours
+from rastr.gis.fishnet import create_fishnet
+from rastr.gis.smooth import catmull_rom_smooth
+from rastr.meta import RasterMeta
+
+if TYPE_CHECKING:
+    from folium import Map
+
+try:
+    import folium
+    import folium.raster_layers
+    from folium import Map
+except ImportError:
+    FOLIUM_INSTALLED = False
+else:
+    FOLIUM_INSTALLED = True
+
+try:
+    from rasterio._err import CPLE_BaseError
+except ImportError:
+    CPLE_BaseError = Exception  # Fallback if private module import fails
+
+
+CTX_BASEMAP_SOURCE = xyz.Esri.WorldImagery  # pyright: ignore[reportAttributeAccessIssue]
+
+
+class RasterCellArrayShapeError(ValueError):
+    """Custom error for invalid raster cell array shapes."""
+
+
+class RasterModel(BaseModel):
+    """2-dimensional raster and metadata."""
+
+    arr: InstanceOf[np.ndarray]
+    raster_meta: RasterMeta
+
+    def __eq__(self, other: object) -> bool:
+        """Check equality of two RasterModel objects."""
+        if not isinstance(other, RasterModel):
+            return NotImplemented
+        return (
+            np.array_equal(self.arr, other.arr)
+            and self.raster_meta == other.raster_meta
+        )
+
+    __hash__ = BaseModel.__hash__
+
+    def __add__(self, other: float | Self) -> Self:
+        if isinstance(other, float | int):
+            new_arr = self.arr + other
+            return RasterModel(arr=new_arr, raster_meta=self.raster_meta)
+        elif isinstance(other, RasterModel):
+            if self.raster_meta != other.raster_meta:
+                msg = (
+                    "Rasters must have the same metadata (e.g. CRS, cell size, etc.) "
+                    "to be added"
+                )
+                raise ValueError(msg)
+            if self.arr.shape != other.arr.shape:
+                msg = (
+                    "Rasters must have the same shape to be added:\n"
+                    f"{self.arr.shape} != {other.arr.shape}"
+                )
+                raise ValueError(msg)
+            new_arr = self.arr + other.arr
+            return RasterModel(arr=new_arr, raster_meta=self.raster_meta)
+        else:
+            return NotImplemented
+
+    def __radd__(self, other: float) -> Self:
+        return self + other
+
+    def __mul__(self, other: float | Self) -> Self:
+        if isinstance(other, float | int):
+            new_arr = self.arr * other
+            return RasterModel(arr=new_arr, raster_meta=self.raster_meta)
+        elif isinstance(other, RasterModel):
+            if self.raster_meta != other.raster_meta:
+                msg = (
+                    "Rasters must have the same metadata (e.g. CRS, cell size, etc.) "
+                    "to be multiplied"
+                )
+                raise ValueError(msg)
+            if self.arr.shape != other.arr.shape:
+                msg = "Rasters must have the same shape to be multiplied"
+                raise ValueError(msg)
+            new_arr = self.arr * other.arr
+            return RasterModel(arr=new_arr, raster_meta=self.raster_meta)
+        else:
+            return NotImplemented
+
+    def __rmul__(self, other: float) -> Self:
+        return self * other
+
+    def __truediv__(self, other: float | Self) -> Self:
+        if isinstance(other, float | int):
+            new_arr = self.arr / other
+            return RasterModel(arr=new_arr, raster_meta=self.raster_meta)
+        elif isinstance(other, RasterModel):
+            if self.raster_meta != other.raster_meta:
+                msg = (
+                    "Rasters must have the same metadata (e.g. CRS, cell size, etc.) "
+                    "to be divided"
+                )
+                raise ValueError(msg)
+            if self.arr.shape != other.arr.shape:
+                msg = "Rasters must have the same shape to be divided"
+                raise ValueError(msg)
+            new_arr = self.arr / other.arr
+            return RasterModel(arr=new_arr, raster_meta=self.raster_meta)
+        else:
+            return NotImplemented
+
+    def __rtruediv__(self, other: float) -> Self:
+        return self / other
+
+    def __sub__(self, other: float | Self) -> Self:
+        return self + (-other)
+
+    def __rsub__(self, other: float) -> Self:
+        return -self + other
+
+    def __neg__(self) -> Self:
+        return RasterModel(arr=-self.arr, raster_meta=self.raster_meta)
+
+    @property
+    def cell_centre_coords(self) -> NDArray[np.float64]:
+        """Get the coordinates of the cell centres in the raster."""
+        return self.raster_meta.get_cell_centre_coords(self.arr.shape)
+
+    @contextmanager
+    def to_rasterio_dataset(
+        self,
+    ) -> Generator[DatasetReader | BufferedDatasetWriter | DatasetWriter]:
+        """Create a rasterio in-memory dataset from the Raster object.
+
+        Example:
+            >>> raster = RasterModel.example()
+            >>> with raster.to_rasterio_dataset() as dataset:
+            >>>     ...
+        """
+        memfile = MemoryFile()
+
+        height, width = self.arr.shape
+
+        try:
+            with memfile.open(
+                driver="GTiff",
+                height=height,
+                width=width,
+                count=1,  # Assuming a single band; adjust as necessary
+                dtype=self.arr.dtype,
+                crs=self.raster_meta.crs.to_wkt(),
+                transform=self.raster_meta.transform,
+            ) as dataset:
+                dataset.write(self.arr, 1)
+
+            # Yield the dataset for reading
+            with memfile.open() as dataset:
+                yield dataset
+        finally:
+            memfile.close()
+
+    def sample(
+        self,
+        xy: list[tuple[float, float]],
+        *,
+        na_action: Literal["raise", "ignore"] = "raise",
+    ) -> NDArray[np.float64]:
+        """Sample raster values at GeoSeries locations and return sampled values.
+
+        Args:
+            xy: A list of (x, y) coordinates to sample the raster at.
+            na_action: Action to take when a NaN value is encountered in the input xy.
+                       Options are "raise" (raise an error) or "ignore" (replace with
+                       NaN).
+
+        Returns:
+            A list of sampled raster values for each geometry in the GeoSeries.
+        """
+        # If this function is too slow, consider the optimizations detailed here:
+        # https://rdrn.me/optimising-sampling/
+
+        # Short-circuit
+        if len(xy) == 0:
+            return np.array([], dtype=float)
+
+        # Create in-memory rasterio dataset from the incumbent Raster object
+        with self.to_rasterio_dataset() as dataset:
+            if dataset.count != 1:
+                msg = "Only single band rasters are supported."
+                raise NotImplementedError(msg)
+
+            xy_arr = np.array(xy)
+
+            # Determine the indexes of any x,y coordinates where either is NaN.
+            # We will drop these indexes for the purposes of calling .sample, but
+            # then we will add NaN values back in at the end, inserting NaN into the
+            # results array.
+            xy_is_nan = np.isnan(xy_arr).any(axis=1)
+            xy_nan_idxs = list(np.atleast_1d(np.squeeze(np.nonzero(xy_is_nan))))
+            xy_arr = xy_arr[~xy_is_nan]
+
+            if na_action == "raise" and len(xy_nan_idxs) > 0:
+                nan_error_msg = "NaN value found in input coordinates"
+                raise ValueError(nan_error_msg)
+
+            # Sample the raster in-memory dataset (e.g. PGA values) at the coordinates
+            samples = list(
+                rasterio.sample.sample_gen(
+                    dataset,
+                    xy_arr,
+                    indexes=1,  # Single band raster, N.B. rasterio is 1-indexed
+                    masked=True,
+                )
+            )
+
+            # Convert the sampled values to a NumPy array and set masked values to NaN
+            raster_values = np.array(
+                [s.data[0] if not s.mask else np.nan for s in samples]
+            ).astype(float)
+
+            if len(xy_nan_idxs) > 0:
+                # Insert NaN values back into the results array
+                # This is tricky because all the indexes get offset once we remove
+                # elements.
+                offset_xy_nan_idxs = xy_nan_idxs - np.arange(len(xy_nan_idxs))
+                raster_values = np.insert(
+                    raster_values,
+                    offset_xy_nan_idxs,
+                    np.nan,
+                    axis=0,
+                )
+
+        return raster_values
+
+    @property
+    def bounds(self) -> tuple[float, float, float, float]:
+        """Bounding box of the raster as (xmin, ymin, xmax, ymax)"""
+        x1, y1, x2, y2 = rasterio.transform.array_bounds(
+            height=self.arr.shape[0],
+            width=self.arr.shape[1],
+            transform=self.raster_meta.transform,
+        )
+        xmin, xmax = sorted([x1, x2])
+        ymin, ymax = sorted([y1, y2])
+        return (xmin, ymin, xmax, ymax)
+
+    @property
+    def bbox(self) -> Polygon:
+        """Bounding box of the raster as a shapely polygon."""
+        xmin, ymin, xmax, ymax = self.bounds
+        return Polygon(
+            [
+                (xmin, ymin),
+                (xmin, ymax),
+                (xmax, ymax),
+                (xmax, ymin),
+                (xmin, ymin),
+            ]
+        )
+
+    def explore(
+        self,
+        *,
+        m: Map | None = None,
+        opacity: float = 1.0,
+        colormap: str = "viridis",
+    ) -> Map:
+        """Display the raster on a folium map."""
+        if not FOLIUM_INSTALLED:
+            msg = "The 'folium' package is required for 'explore()'."
+            raise ImportError(msg)
+
+        if m is None:
+            m = folium.Map()
+
+        rbga_map: Callable[[float], tuple[float, float, float, float]] = mpl.colormaps[
+            colormap
+        ]
+
+        wgs84_crs = CRS.from_epsg(4326)
+        gdf = gpd.GeoDataFrame(geometry=[self.bbox], crs=self.raster_meta.crs).to_crs(
+            wgs84_crs
+        )
+        xmin, ymin, xmax, ymax = gdf.total_bounds
+
+        arr = np.array(self.arr)
+
+        # Normalize the data to the range [0, 1] as this is the cmap range
+        min_val = np.nanmin(arr)
+        max_val = np.nanmax(arr)
+        if max_val > min_val:  # Prevent division by zero
+            arr = (arr - min_val) / (max_val - min_val)
+        else:
+            arr = np.zeros_like(arr)  # In case all values are the same
+
+        # Finally, need to determine whether to flip the image based on negative Affine
+        # coefficients
+        flip_x = self.raster_meta.transform.a < 0
+        flip_y = self.raster_meta.transform.e > 0
+        if flip_x:
+            arr = np.flip(self.arr, axis=1)
+        if flip_y:
+            arr = np.flip(self.arr, axis=0)
+
+        img = folium.raster_layers.ImageOverlay(
+            image=arr,
+            bounds=[[ymin, xmin], [ymax, xmax]],
+            opacity=opacity,
+            colormap=rbga_map,
+            mercator_project=True,
+        )
+
+        img.add_to(m)
+
+        m.fit_bounds([[ymin, xmin], [ymax, xmax]])
+
+        return m
+
+    def to_clipboard(self) -> None:
+        """Copy the raster cell array to the clipboard."""
+        pd.DataFrame(self.arr).to_clipboard(index=False, header=False)
+
+    def plot(
+        self,
+        *,
+        ax: Axes | None = None,
+        cbar_label: str | None = None,
+        basemap: bool = False,
+        cmap: str = "viridis",
+    ) -> Axes:
+        """Plot the raster on a matplotlib axis."""
+        if ax is None:
+            _, ax = plt.subplots()
+        ax: Axes
+
+        if basemap:
+            msg = "Basemap plotting is not yet implemented."
+            raise NotImplementedError(msg)
+
+        arr = self.arr.copy()
+
+        # Get extent of the non-zero values in array index coordinates
+        (x_nonzero,) = np.nonzero(arr.any(axis=0))
+        (y_nonzero,) = np.nonzero(arr.any(axis=1))
+
+        if len(x_nonzero) == 0 or len(y_nonzero) == 0:
+            msg = "Raster contains no non-zero values; cannot plot."
+            raise ValueError(msg)
+
+        min_x_nonzero = np.min(x_nonzero)
+        max_x_nonzero = np.max(x_nonzero)
+        min_y_nonzero = np.min(y_nonzero)
+        max_y_nonzero = np.max(y_nonzero)
+
+        # Transform to raster CRS
+        x1, y1 = self.raster_meta.transform * (min_x_nonzero, min_y_nonzero)
+        x2, y2 = self.raster_meta.transform * (max_x_nonzero, max_y_nonzero)
+        xmin, xmax = sorted([x1, x2])
+        ymin, ymax = sorted([y1, y2])
+
+        arr[arr == 0] = np.nan
+
+        with self.to_rasterio_dataset() as dataset:
+            img, *_ = rasterio.plot.show(
+                dataset, with_bounds=True, ax=ax, cmap=cmap
+            ).get_images()
+
+        ax.set_xlim(xmin, xmax)
+        ax.set_ylim(ymin, ymax)
+
+        ax.set_aspect("equal", "box")
+        ax.set_yticklabels([])
+        ax.set_xticklabels([])
+
+        divider = make_axes_locatable(ax)
+        cax = divider.append_axes("right", size="5%", pad=0.05)
+        fig = ax.get_figure()
+        fig.colorbar(img, label=cbar_label, cax=cax)
+        return ax
+
+    def as_geodataframe(self, name: str = "value") -> gpd.GeoDataFrame:
+        """Create a GeoDataFrame representation of the raster."""
+        polygons = create_fishnet(bounds=self.bounds, res=self.raster_meta.cell_size)
+        point_tuples = [polygon.centroid.coords[0] for polygon in polygons]
+        raster_gdf = gpd.GeoDataFrame(
+            {
+                "geometry": polygons,
+                name: self.sample(point_tuples, na_action="ignore"),
+            },
+            crs=self.raster_meta.crs,
+        )
+
+        return raster_gdf
+
+    def to_file(self, path: Path) -> None:
+        """Write the raster to a GeoTIFF file."""
+
+        suffix = path.suffix.lower()
+        if suffix in (".tif", ".tiff"):
+            driver = "GTiff"
+        elif suffix in (".grd"):
+            # https://grapherhelp.goldensoftware.com/subsys/ascii_grid_file_format.htm
+            # e.g. Used by AnAqSim
+            driver = "GSAG"
+        else:
+            msg = f"Unsupported file extension: {suffix}"
+            raise ValueError(msg)
+
+        with rasterio.open(
+            path,
+            "w",
+            driver=driver,
+            height=self.arr.shape[0],
+            width=self.arr.shape[1],
+            count=1,
+            dtype=self.arr.dtype,
+            crs=self.raster_meta.crs,
+            transform=self.raster_meta.transform,
+            nodata=np.nan,
+        ) as dst:
+            try:
+                dst.write(self.arr, 1)
+            except CPLE_BaseError as err:
+                msg = f"Failed to write raster to file: {err}"
+                raise OSError(msg) from err
+
+    def __str__(self) -> str:
+        mean = np.nanmean(self.arr)
+        return f"RasterModel(shape={self.arr.shape}, {mean=})"
+
+    def __repr__(self) -> str:
+        return str(self)
+
+    @classmethod
+    def example(cls) -> Self:
+        """Create an example RasterModel."""
+        # Peaks dataset style example
+        n = 256
+        x = np.linspace(-3, 3, n)
+        y = np.linspace(-3, 3, n)
+        x, y = np.meshgrid(x, y)
+        z = np.exp(-(x**2) - y**2) * np.sin(3 * np.sqrt(x**2 + y**2))
+        arr = z.astype(np.float32)
+
+        raster_meta = RasterMeta.example()
+        return cls(arr=arr, raster_meta=raster_meta)
+
+    def fillna(self, value: float) -> Self:
+        """Fill NaN values in the raster with a specified value.
+
+        See also `extrapolate()` for filling NaN values using extrapolation from data.
+        """
+        filled_arr = np.nan_to_num(self.arr, nan=value)
+        new_raster = self.model_copy()
+        new_raster.arr = filled_arr
+        return new_raster
+
+    def get_xy(self) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
+        """Get the x and y coordinates of the raster in meshgrid format."""
+        col_idx, row_idx = np.meshgrid(
+            np.arange(self.arr.shape[1]),
+            np.arange(self.arr.shape[0]),
+        )
+
+        col_idx = col_idx.flatten()
+        row_idx = row_idx.flatten()
+
+        coords = np.vstack((row_idx, col_idx)).T
+
+        x, y = rasterio.transform.xy(self.raster_meta.transform, *coords.T)
+        x = np.array(x).reshape(self.arr.shape)
+        y = np.array(y).reshape(self.arr.shape)
+        return x, y
+
+    def contour(
+        self, *, levels: list[float], smoothing: bool = True
+    ) -> gpd.GeoDataFrame:
+        """Create contour lines from the raster data, optionally with smoothing.
+
+        The contour lines are returned as a GeoDataFrame with the contours as linestring
+        geometries and the contour levels as attributes in a column named 'level'.
+
+        Consider calling `blur()` before this method to smooth the raster data before
+        contouring, to denoise the contours.
+
+        Args:
+            levels: A list of contour levels to generate. The contour lines will be
+                    generated for each level in this list.
+            smoothing: Defaults to true, which corresponds to applying a smoothing
+                       algorithm to the contour lines. At the moment, this is the
+                       Catmull-Rom spline algorithm. If set to False, the raw
+                       contours will be returned without any smoothing.
+        """
+
+        all_levels = []
+        all_geoms = []
+        for level in levels:
+            contours = skimage.measure.find_contours(
+                self.arr,
+                level=level,
+            )
+
+            # Constructg shapely LineString objects
+            # Convert to CRS from array index coordinates to raster CRS
+            geoms = [
+                LineString(
+                    np.array(
+                        rasterio.transform.xy(self.raster_meta.transform, *contour.T)
+                    ).T
+                )
+                for contour in contours
+                # Contour lines need at least three distinct points to avoid
+                # degenerate geometries
+                if np.unique(contour, axis=0).shape[0] > 2
+            ]
+
+            # Apply smoothing if requested
+            if smoothing:
+                geoms = [catmull_rom_smooth(geom) for geom in geoms]
+
+            all_geoms.extend(geoms)
+            all_levels.extend([level] * len(geoms))
+
+        contour_gdf = gpd.GeoDataFrame(
+            data={
+                "level": all_levels,
+            },
+            geometry=all_geoms,
+            crs=self.raster_meta.crs,
+        )
+
+        return contour_gdf
+
+    def blur(self, sigma: float) -> Self:
+        """Apply a Gaussian blur to the raster data.
+
+        Args:
+            sigma: Standard deviation for Gaussian kernel, in units of geographic
+                   coordinate distance (e.g. meters). A larger sigma results in a more
+                   blurred image.
+        """
+
+        cell_sigma = sigma / self.raster_meta.cell_size
+
+        blurred_array = gaussian_filter(self.arr, sigma=cell_sigma)
+        new_raster = self.model_copy()
+        new_raster.arr = blurred_array
+        return new_raster
+
+    def extrapolate(self, method: Literal["nearest"] = "nearest") -> Self:
+        """Extrapolate the raster data to fill NaN values.
+
+        See also `fillna()` for filling NaN values with a specific value.
+
+        If the raster is all-NaN, this method will return a copy of the raster without
+        changing the NaN values.
+
+        Args:
+            method: The method to use for extrapolation. Currently only 'nearest' is
+                    supported, which fills NaN values with the nearest non-NaN value.
+        """
+        if method not in ("nearest",):
+            msg = f"Unsupported extrapolation method: {method}"
+            raise NotImplementedError(msg)
+
+        raster = self.model_copy()
+        raster.arr = fillna_nearest_neighbours(arr=self.arr)
+
+        return raster
+
+    def resample(
+        self, new_cell_size: float, *, method: Literal["bilinear"] = "bilinear"
+    ) -> Self:
+        """Resample the raster data to a new resolution.
+
+        If the new cell size is not an exact multiple of the current cell size, the
+        overall raster bounds may increase slightly. The affine transform will keep
+        the same shift, i.e. the top-left corner of the raster will remain in the same'
+        coordinate location. A corollary is that the overall centre of the raster bounds
+        will not necessary be the same as the original raster.
+
+        Args:
+            new_cell_size: The desired cell size for the resampled raster.
+            method: The resampling method to use. Only 'bilinear' is supported.
+        """
+        if method not in ("bilinear",):
+            msg = f"Unsupported resampling method: {method}"
+            raise NotImplementedError(msg)
+
+        factor = self.raster_meta.cell_size / new_cell_size
+
+        # Use the rasterio dataset with proper context management
+        with self.to_rasterio_dataset() as dataset:
+            # N.B. the new height and width may increase slightly.
+            new_height = int(np.ceil(dataset.height * factor))
+            new_width = int(np.ceil(dataset.width * factor))
+
+            # Resample via rasterio
+            (new_arr,) = dataset.read(  # Assume exactly one band
+                out_shape=(dataset.count, new_height, new_width),
+                resampling=Resampling.bilinear,
+            )
+
+            # Create new RasterMeta with updated transform and cell size
+            new_raster_meta = RasterMeta(
+                transform=dataset.transform
+                * dataset.transform.scale(
+                    (dataset.width / new_width),
+                    (dataset.height / new_height),
+                ),
+                crs=self.raster_meta.crs,
+                cell_size=new_cell_size,
+            )
+
+            return RasterModel(arr=new_arr, raster_meta=new_raster_meta)
+
+    @field_validator("arr")
+    @classmethod
+    def check_2d_array(cls, v: np.ndarray) -> np.ndarray:
+        """Validator to ensure the cell array is 2D."""
+        if v.ndim != 2:
+            msg = "Cell array must be 2D"
+            raise RasterCellArrayShapeError(msg)
+        return v

rastr-0.1.0.dist-info/METADATA

@@ -0,0 +1,44 @@
+Metadata-Version: 2.4
+Name: rastr
+Version: 0.1.0
+Summary: Geospatial Raster datatype library for Python.
+Project-URL: Source Code, https://github.com/tonkintaylor/rastr
+Project-URL: Bug Tracker, https://github.com/tonkintaylor/rastr/issues
+Project-URL: Releases, https://github.com/tonkintaylor/rastr/releases
+Project-URL: Source Archive, https://github.com/tonkintaylor/rastr/archive/ac9cfaefef4030485d30ce79b97a000821338bd2.zip
+Author-email: Tonkin & Taylor Limited <Sub-DisciplineData+AnalyticsStaff@tonkintaylor.co.nz>, Nathan McDougall <nmcdougall@tonkintaylor.co.nz>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: affine>=2.4.0
+Requires-Dist: folium>=0.20.0
+Requires-Dist: geopandas>=1.1.1
+Requires-Dist: matplotlib>=3.10.5
+Requires-Dist: numpy>=2.2.6
+Requires-Dist: pandas>=2.3.1
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: pyproj>=3.7.1
+Requires-Dist: rasterio>=1.4.3
+Requires-Dist: scikit-image>=0.25.2
+Requires-Dist: scipy>=1.15.3
+Requires-Dist: shapely>=2.1.1
+Requires-Dist: tqdm>=4.67.1
+Requires-Dist: typing-extensions>=4.14.1
+Requires-Dist: xyzservices>=2025.4.0
+Description-Content-Type: text/markdown
+
+# Rastr
+
+[![PyPI Version](https://img.shields.io/pypi/v/rastr.svg)](<https://pypi.python.org/pypi/rastr>)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![usethis](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/usethis-python/usethis-python/main/assets/badge/v1.json)](https://github.com/usethis-python/usethis-python)
+
+Geospatial Raster datatype library for Python.
+
+Currently, only single-banded rasters with square cells are supported.

rastr-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+rastr/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rastr/_version.py,sha256=-LyU5F1uZDjn6Q8_Z6-_FJt_8RE4Kq9zcKdg1abSSps,511
+rastr/create.py,sha256=tHLVnGarMt04p1z8CVknMWMjQLKrb0WrcP_Wgdw8xr4,9346
+rastr/io.py,sha256=GLj2o26L2bLLXys2wTSKk1mM-FRDciOt7Ty7r87gVg4,961
+rastr/meta.py,sha256=b_knC8a5qWcAZKm8RrZ7bYTLuOtfGQsIp73JMcq8cU0,1384
+rastr/raster.py,sha256=PzmMLJqf6nhYNu81dqLJ9iZpkxOBrn02FtI-5o3meL4,22996
+rastr/arr/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rastr/arr/fill.py,sha256=7N3ECMli7ssNJJk5qgDoj_3xExgu03nohGPgUKWxcCk,903
+rastr/gis/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rastr/gis/fishnet.py,sha256=LZqtI9cgYPacuWNfIfdbTkRMRSnJCQdYlaT2eVPmorM,2459
+rastr/gis/smooth.py,sha256=LbWvAG1O-O5H6P5LrbwD03mbnXVYjkH1re-_iZ4arIU,4754
+rastr-0.1.0.dist-info/METADATA,sha256=IKTH8nVmhO3FRMTHWKk0zpdxt5kxw5giusz-7perakI,2143
+rastr-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+rastr-0.1.0.dist-info/licenses/LICENSE,sha256=7qUsx93G2ATTRLZiSYuQofwAX_uWvrqnAiMK8PzxvNc,1080
+rastr-0.1.0.dist-info/RECORD,,

rastr-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

rastr-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tonkin + Taylor Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.