yirgacheffe 1.4.0__py3-none-any.whl → 1.5.0__py3-none-any.whl

yirgacheffe/__init__.py

@@ -5,10 +5,7 @@ try:
 except ModuleNotFoundError:
     __version__ = "unknown"
 
-gdal.UseExceptions()
+from ._core import read_raster, read_rasters, read_shape, read_shape_like
+from .constants import WGS_84_PROJECTION
 
-# I don't really want this here, but it's just too useful having it exposed
-WGS_84_PROJECTION = 'GEOGCS["WGS 84",DATUM["WGS_1984",SPHEROID["WGS 84",6378137,298.257223563,'\
-    'AUTHORITY["EPSG","7030"]],AUTHORITY["EPSG","6326"]],PRIMEM["Greenwich",0],'\
-    'UNIT["degree",0.0174532925199433,AUTHORITY["EPSG","9122"]],AXIS["Latitude",NORTH],'\
-    'AXIS["Longitude",EAST],AUTHORITY["EPSG","4326"]]'
+gdal.UseExceptions()

yirgacheffe/_backends/mlx.py

@@ -1,3 +1,4 @@
+from typing import Callable, Dict
 
 import numpy as np
 import mlx.core as mx # type: ignore
@@ -182,7 +183,7 @@ def backend_to_dtype(val):
 def astype_op(data, datatype):
     return data.astype(dtype_to_backed(datatype))
 
-operator_map = {
+operator_map : Dict[op,Callable] = {
     op.ADD: mx.array.__add__,
     op.SUB: mx.array.__sub__,
     op.MUL: mul_op,

yirgacheffe/_backends/numpy.py

@@ -1,3 +1,4 @@
+from typing import Callable, Dict
 
 import numpy as np
 import torch
@@ -120,7 +121,7 @@ def backend_to_dtype(val):
 def astype_op(data, datatype):
     return data.astype(dtype_to_backed(datatype))
 
-operator_map = {
+operator_map : Dict[op,Callable] = {
     op.ADD: np.ndarray.__add__,
     op.SUB: np.ndarray.__sub__,
     op.MUL: np.ndarray.__mul__,

yirgacheffe/_core.py

@@ -0,0 +1,133 @@
+from pathlib import Path
+from typing import List, Optional, Tuple, Union
+
+from .layers.base import YirgacheffeLayer
+from .layers.group import GroupLayer, TiledGroupLayer
+from .layers.rasters import RasterLayer
+from .layers.vectors import VectorLayer
+from .window import PixelScale
+from .operators import DataType
+
+def read_raster(
+    filename: Union[Path,str],
+    band: int = 1
+) -> RasterLayer:
+    """Open a raster file (e.g., GeoTIFF).
+
+    Parameters
+    ----------
+    filename : Path
+        Path of raster file to open.
+    band : int, default=1
+        For multi-band rasters, which band to use (defaults to first if not specified).
+
+    Returns
+    -------
+    RasterLayer
+        Returns an layer representing the raster data.
+    """
+    return RasterLayer.layer_from_file(filename, band)
+
+def read_rasters(
+    filenames : Union[List[Path],List[str]],
+    tiled: bool=False
+) -> GroupLayer:
+    """Open a set of raster files (e.g., GeoTIFFs) as a single layer.
+
+    Parameters
+    ----------
+    filenames : List[Path]
+        List of paths of raster files to open.
+    tiled : bool, default=False
+        If you know that the rasters for a regular tileset, then setting this flag allows
+        Yirgacheffe to perform certain optimisations that significantly improve performance for
+        this use case.
+
+    Returns
+    -------
+    GroupLayer
+        Returns an layer representing the raster data.
+    """
+    if not tiled:
+        return GroupLayer.layer_from_files(filenames)
+    else:
+        return TiledGroupLayer.layer_from_files(filenames)
+
+def read_shape(
+    filename: Union[Path,str],
+    scale: Union[PixelScale, Tuple[float,float]],
+    projection: str,
+    where_filter: Optional[str] = None,
+    datatype: Optional[DataType] = None,
+    burn_value: Union[int,float,str] = 1,
+) -> VectorLayer:
+    """Open a polygon file (e.g., GeoJSON, GPKG, or ESRI Shape File).
+
+    Parameters
+    ----------
+    filename : Path
+        Path of raster file to open.
+    scale: PixelScale or tuple of float
+        The dimensions of each pixel.
+    projection: str
+        The map projection to use
+    where_filter : str, optional
+        For use with files with many entries (e.g., GPKG), applies this filter to the data.
+    datatype: DataType, default=DataType.Byte
+        Specify the data type of the raster data generated.
+    burn_value: int or float or str, default=1
+        The value of each pixel in the polygon.
+
+    Returns
+    -------
+    VectorLayer
+        Returns an layer representing the vector data.
+    """
+
+    if not isinstance(scale, PixelScale):
+        scale = PixelScale(scale[0], scale[1])
+
+    return VectorLayer.layer_from_file(
+        filename,
+        where_filter,
+        scale,
+        projection,
+        datatype,
+        burn_value
+    )
+
+def read_shape_like(
+    filename: Union[Path,str],
+    like: YirgacheffeLayer,
+    where_filter: Optional[str] = None,
+    datatype: Optional[DataType] = None,
+    burn_value: Union[int,float,str] = 1,
+) -> VectorLayer:
+    """Open a polygon file (e.g., GeoJSON, GPKG, or ESRI Shape File).
+
+    Parameters
+    ----------
+    filename : Path
+        Path of raster file to open.
+    like: YirgacheffeLayer
+        Another layer that has a projection and pixel scale set. This layer will
+        use the same projection and pixel scale as that one.
+    where_filter : str, optional
+        For use with files with many entries (e.g., GPKG), applies this filter to the data.
+    datatype: DataType, default=DataType.Byte
+        Specify the data type of the raster data generated.
+    burn_value: int or float or str, default=1
+        The value of each pixel in the polygon.
+
+    Returns
+    -------
+    VectorLayer
+        Returns an layer representing the vector data.
+    """
+    return VectorLayer.layer_from_file_like(
+        filename,
+        like,
+        where_filter,
+        datatype,
+        burn_value,
+    )

yirgacheffe/constants.py

@@ -1,2 +1,8 @@
 YSTEP = 512
 MINIMUM_CHUNKS_PER_THREAD = 1
+
+# I don't really want this here, but it's just too useful having it exposed
+WGS_84_PROJECTION = 'GEOGCS["WGS 84",DATUM["WGS_1984",SPHEROID["WGS 84",6378137,298.257223563,'\
+	'AUTHORITY["EPSG","7030"]],AUTHORITY["EPSG","6326"]],PRIMEM["Greenwich",0],'\
+	'UNIT["degree",0.0174532925199433,AUTHORITY["EPSG","9122"]],AXIS["Latitude",NORTH],'\
+	'AXIS["Longitude",EAST],AUTHORITY["EPSG","4326"]]'

yirgacheffe/layers/base.py

@@ -1,5 +1,5 @@
-
-from typing import Any, List, Optional, Tuple
+from __future__ import annotations
+from typing import Any, Optional, Sequence, Tuple
 
 from ..operators import DataType, LayerMathMixin
 from ..rounding import almost_equal, are_pixel_scales_equal_enough, round_up_pixels, round_down_pixels
@@ -67,7 +67,7 @@ class YirgacheffeLayer(LayerMathMixin):
         return self._window
 
     @staticmethod
-    def find_intersection(layers: List) -> Area:
+    def find_intersection(layers: Sequence[YirgacheffeLayer]) -> Area:
         if not layers:
             raise ValueError("Expected list of layers")
 
@@ -87,7 +87,7 @@ class YirgacheffeLayer(LayerMathMixin):
         return intersection
 
     @staticmethod
-    def find_union(layers: List) -> Area:
+    def find_union(layers: Sequence[YirgacheffeLayer]) -> Area:
         if not layers:
             raise ValueError("Expected list of layers")
 
@@ -183,7 +183,7 @@ class YirgacheffeLayer(LayerMathMixin):
         self._window = new_window
         self._active_area = new_area
 
-    def reset_window(self):
+    def reset_window(self) -> None:
         self._active_area = self._underlying_area
         if self._pixel_scale:
             abs_xstep, abs_ystep = abs(self._pixel_scale.xstep), abs(self._pixel_scale.ystep)
@@ -194,7 +194,7 @@ class YirgacheffeLayer(LayerMathMixin):
                 ysize=round_up_pixels((self.area.bottom - self.area.top) / self._pixel_scale.ystep, abs_ystep),
             )
 
-    def offset_window_by_pixels(self, offset: int):
+    def offset_window_by_pixels(self, offset: int) -> None:
         """Grows (if pixels is positive) or shrinks (if pixels is negative) the window for the layer."""
         if offset == 0:
             return

yirgacheffe/layers/constant.py

@@ -4,19 +4,14 @@ from ..operators import DataType
 from ..window import Area, PixelScale, Window
 from .base import YirgacheffeLayer
 from .._backends import backend
-from .. import WGS_84_PROJECTION
+from ..constants import WGS_84_PROJECTION
 
 
 class ConstantLayer(YirgacheffeLayer):
     """This is a layer that will return the identity value - can be used when an input layer is
     missing (e.g., area) without having the calculation full of branches."""
     def __init__(self, value: Union[int,float]): # pylint: disable=W0231
-        area = Area(
-            left = -180.0,
-            top = 90.0,
-            right = 180.0,
-            bottom = -90.0
-        )
+        area = Area.world()
         super().__init__(area, None, WGS_84_PROJECTION)
         self.value = float(value)
 

yirgacheffe/layers/group.py

@@ -1,8 +1,7 @@
 from __future__ import annotations
 import copy
-import glob
-import os
-from typing import Any, List, Optional
+from pathlib import Path
+from typing import Any, List, Optional, Union
 
 import numpy as np
 from yirgacheffe.operators import DataType
@@ -23,19 +22,25 @@ class GroupLayer(YirgacheffeLayer):
     @classmethod
     def layer_from_directory(
         cls,
-        directory_path: str,
+        directory_path: Union[Path,str],
         name: Optional[str] = None,
         matching: str = "*.tif"
     ) -> GroupLayer:
         if directory_path is None:
             raise ValueError("Directory path is None")
-        files = [os.path.join(directory_path, x) for x in glob.glob(matching, root_dir=directory_path)]
+        if isinstance(directory_path, str):
+            directory_path = Path(directory_path)
+        files = list(directory_path.glob(matching))
         if len(files) < 1:
             raise GroupLayerEmpty(directory_path)
         return cls.layer_from_files(files, name)
 
     @classmethod
-    def layer_from_files(cls, filenames: List[str], name: Optional[str] = None) -> GroupLayer:
+    def layer_from_files(
+        cls,
+        filenames: Union[List[Path],List[str]],
+        name: Optional[str] = None
+    ) -> GroupLayer:
         if filenames is None:
             raise ValueError("filenames argument is None")
         if len(filenames) < 1:
@@ -43,7 +48,11 @@ class GroupLayer(YirgacheffeLayer):
         rasters: List[YirgacheffeLayer] = [RasterLayer.layer_from_file(x) for x in filenames]
         return cls(rasters, name)
 
-    def __init__(self, layers: List[YirgacheffeLayer], name: Optional[str] = None) -> None:
+    def __init__(
+        self,
+        layers: List[YirgacheffeLayer],
+        name: Optional[str] = None
+    ) -> None:
         if not layers:
             raise GroupLayerEmpty("Expected one or more layers")
         if not are_pixel_scales_equal_enough([x.pixel_scale for x in layers]):

yirgacheffe/layers/rasters.py

@@ -1,12 +1,12 @@
 from __future__ import annotations
 import math
-import os
+from pathlib import Path
 from typing import Any, Optional, Tuple, Union
 
 import numpy as np
 from osgeo import gdal
 
-from .. import WGS_84_PROJECTION
+from ..constants import WGS_84_PROJECTION
 from ..window import Area, PixelScale, Window
 from ..rounding import round_up_pixels
 from .base import YirgacheffeLayer
@@ -88,7 +88,7 @@ class RasterLayer(YirgacheffeLayer):
     @staticmethod
     def empty_raster_layer_like(
         layer: Any,
-        filename: Optional[str]=None,
+        filename: Optional[Union[Path,str]]=None,
         area: Optional[Area]=None,
         datatype: Optional[Union[int, DataType]]=None,
         compress: bool=True,
@@ -214,7 +214,7 @@ class RasterLayer(YirgacheffeLayer):
         return RasterLayer(dataset)
 
     @classmethod
-    def layer_from_file(cls, filename: str, band: int = 1) -> RasterLayer:
+    def layer_from_file(cls, filename: Union[Path,str], band: int = 1) -> RasterLayer:
         try:
             dataset = gdal.Open(filename, gdal.GA_ReadOnly)
         except RuntimeError as exc:
@@ -224,7 +224,7 @@ class RasterLayer(YirgacheffeLayer):
             _ = dataset.GetRasterBand(band)
         except RuntimeError as exc:
             raise InvalidRasterBand(band) from exc
-        return cls(dataset, filename, band)
+        return cls(dataset, str(filename), band)
 
     def __init__(self, dataset: gdal.Dataset, name: Optional[str] = None, band: int = 1):
         if not dataset:
@@ -252,7 +252,7 @@ class RasterLayer(YirgacheffeLayer):
         assert self.window == Window(0, 0, dataset.RasterXSize, dataset.RasterYSize)
 
         self._dataset = dataset
-        self._dataset_path = dataset.GetDescription()
+        self._dataset_path = Path(dataset.GetDescription())
         self._band = band
         self._raster_xsize = dataset.RasterXSize
         self._raster_ysize = dataset.RasterYSize
@@ -275,7 +275,7 @@ class RasterLayer(YirgacheffeLayer):
 
     def __getstate__(self) -> object:
         # Only support pickling on file backed layers (ideally read only ones...)
-        if not os.path.isfile(self._dataset_path):
+        if not self._dataset_path.exists():
             raise ValueError("Can not pickle layer that is not file backed.")
         odict = self.__dict__.copy()
         self._park()

yirgacheffe/layers/rescaled.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 from math import floor, ceil
-from typing import Any, Optional
+from pathlib import Path
+from typing import Any, Optional, Union
 
 from skimage import transform
 from yirgacheffe.operators import DataType
@@ -17,7 +18,7 @@ class RescaledRasterLayer(YirgacheffeLayer):
     @classmethod
     def layer_from_file(
         cls,
-        filename: str,
+        filename: Union[Path,str],
         pixel_scale: PixelScale,
         band: int = 1,
         nearest_neighbour: bool = True,

yirgacheffe/layers/vectors.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
-import os
 from math import ceil, floor
+from pathlib import Path
 from typing import Any, Optional, Tuple, Union
 from typing_extensions import NotRequired
 
@@ -62,7 +62,7 @@ class RasteredVectorLayer(RasterLayer):
     @classmethod
     def layer_from_file( # type: ignore[override] # pylint: disable=W0221
         cls,
-        filename: str,
+        filename: Union[Path,str],
         where_filter: Optional[str],
         scale: PixelScale,
         projection: str,
@@ -172,7 +172,7 @@ class VectorLayer(YirgacheffeLayer):
     @classmethod
     def layer_from_file_like(
         cls,
-        filename: str,
+        filename: Union[Path,str],
         other_layer: YirgacheffeLayer,
         where_filter: Optional[str]=None,
         datatype: Optional[Union[int, DataType]] = None,
@@ -198,7 +198,7 @@ class VectorLayer(YirgacheffeLayer):
             layer,
             other_layer.pixel_scale,
             other_layer.projection,
-            name=filename,
+            name=str(filename),
             datatype=datatype if datatype is not None else other_layer.datatype,
             burn_value=burn_value,
             anchor=(other_layer.area.left, other_layer.area.top),
@@ -208,14 +208,14 @@ class VectorLayer(YirgacheffeLayer):
         # a SIGSEGV when using the layers from it later, as some SWIG pointers outlive
         # the original object being around
         vector_layer._original = vectors
-        vector_layer._dataset_path = filename
+        vector_layer._dataset_path = filename if isinstance(filename, Path) else Path(filename)
         vector_layer._filter = where_filter
         return vector_layer
 
     @classmethod
     def layer_from_file(
         cls,
-        filename: str,
+        filename: Union[Path,str],
         where_filter: Optional[str],
         scale: PixelScale,
         projection: str,
@@ -223,9 +223,11 @@ class VectorLayer(YirgacheffeLayer):
         burn_value: Union[int,float,str] = 1,
         anchor: Tuple[float,float] = (0.0, 0.0)
     ) -> VectorLayer:
-        vectors = ogr.Open(filename)
-        if vectors is None:
-            raise FileNotFoundError(filename)
+        try:
+            vectors = ogr.Open(filename)
+        except RuntimeError as exc:
+            # With exceptions on GDAL now returns the wrong (IMHO) exception
+            raise FileNotFoundError(filename) from exc
         layer = vectors.GetLayer()
         if where_filter is not None:
             layer.SetAttributeFilter(where_filter)
@@ -243,7 +245,7 @@ class VectorLayer(YirgacheffeLayer):
             layer,
             scale,
             projection,
-            name=filename,
+            name=str(filename),
             datatype=datatype_arg,
             burn_value=burn_value,
             anchor=anchor
@@ -253,7 +255,7 @@ class VectorLayer(YirgacheffeLayer):
         # a SIGSEGV when using the layers from it later, as some SWIG pointers outlive
         # the original object being around
         vector_layer._original = vectors
-        vector_layer._dataset_path = filename
+        vector_layer._dataset_path = filename if isinstance(filename, Path) else Path(filename)
         vector_layer._filter = where_filter
         return vector_layer
 
@@ -282,7 +284,7 @@ class VectorLayer(YirgacheffeLayer):
         self.burn_value = burn_value
 
         self._original = None
-        self._dataset_path: Optional[str] = None
+        self._dataset_path: Optional[Path] = None
         self._filter: Optional[str] = None
 
         # work out region for mask
@@ -323,7 +325,7 @@ class VectorLayer(YirgacheffeLayer):
 
     def __getstate__(self) -> object:
         # Only support pickling on file backed layers (ideally read only ones...)
-        if self._dataset_path is None or not os.path.isfile(self._dataset_path):
+        if self._dataset_path is None or not self._dataset_path.exists():
             raise ValueError("Can not pickle layer that is not file backed.")
         odict = self.__dict__.copy()
         del odict['_original']

yirgacheffe/operators.py

@@ -1,15 +1,19 @@
 import logging
 import math
 import multiprocessing
+import os
 import sys
+import tempfile
 import time
 import types
 from enum import Enum
 from multiprocessing import Semaphore, Process
 from multiprocessing.managers import SharedMemoryManager
-from typing import Optional
+from pathlib import Path
+from typing import Callable, Dict, Optional, Union
 
 import numpy as np
+import numpy.typing as npt
 from osgeo import gdal
 from dill import dumps, loads # type: ignore
 
@@ -40,6 +44,9 @@ class LayerConstant:
     def _eval(self, _area, _index, _step, _target_window):
         return self.val
 
+    @property
+    def area(self):
+        return Area.world()
 
 class LayerMathMixin:
 
@@ -346,25 +353,19 @@ class LayerOperation(LayerMathMixin):
         self.__dict__.update(state)
 
     @property
-    def area(self) -> Optional[Area]:
+    def area(self) -> Area:
         # The type().__name__ here is to avoid a circular import dependancy
-        lhs_area = self.lhs.area if not type(self.lhs).__name__ == "ConstantLayer" else None
+        lhs_area = self.lhs.area
         try:
-            rhs_area = self.rhs.area if not type(self.rhs).__name__ == "ConstantLayer" else None # type: ignore[return-value] # pylint: disable=C0301
+            rhs_area = self.rhs.area
         except AttributeError:
             rhs_area = None
         try:
-            other_area = self.other.area if not type(self.other).__name__ == "ConstantLayer" else None # type: ignore[return-value] # pylint: disable=C0301
+            other_area = self.other.area
         except AttributeError:
             other_area = None
 
-        all_areas = []
-        if lhs_area is not None:
-            all_areas.append(lhs_area)
-        if rhs_area is not None:
-            all_areas.append(rhs_area)
-        if other_area is not None:
-            all_areas.append(other_area)
+        all_areas = [x for x in [lhs_area, rhs_area, other_area] if (x is not None) and (not x.is_world)]
 
         match self.window_op:
             case WindowOperation.NONE:
@@ -453,7 +454,7 @@ class LayerOperation(LayerMathMixin):
             return lhs_data
 
         try:
-            operator = backend.operator_map[self.operator]
+            operator: Callable = backend.operator_map[self.operator]
         except KeyError:
             # Handles things like `numpy_apply` where a custom operator is provided
             operator = self.operator
@@ -511,7 +512,7 @@ class LayerOperation(LayerMathMixin):
                 res = chunk_max
         return res
 
-    def save(self, destination_layer, and_sum=False, callback=None, band=1):
+    def save(self, destination_layer, and_sum=False, callback=None, band=1) -> Optional[float]:
         """
         Calling save will write the output of the operation to the provied layer.
         If you provide sum as true it will additionall compute the sum and return that.
@@ -608,7 +609,14 @@ class LayerOperation(LayerMathMixin):
         except AttributeError:
             pass
 
-    def _parallel_save(self, destination_layer, and_sum=False, callback=None, parallelism=None, band=1):
+    def _parallel_save(
+        self,
+        destination_layer,
+        and_sum=False,
+        callback=None,
+        parallelism=None,
+        band=1
+    ) -> Optional[float]:
         assert (destination_layer is not None) or and_sum
         try:
             computation_window = self.window
@@ -648,7 +656,7 @@ class LayerOperation(LayerMathMixin):
                     or (computation_window.ysize != destination_window.ysize):
                 raise ValueError("Destination raster window size does not match input raster window size.")
 
-            np_dtype = {
+            np_type_map : Dict[int, np.dtype] = {
                 gdal.GDT_Byte:    np.dtype('byte'),
                 gdal.GDT_Float32: np.dtype('float32'),
                 gdal.GDT_Float64: np.dtype('float64'),
@@ -659,7 +667,8 @@ class LayerOperation(LayerMathMixin):
                 gdal.GDT_UInt16:  np.dtype('uint16'),
                 gdal.GDT_UInt32:  np.dtype('uint32'),
                 gdal.GDT_UInt64:  np.dtype('uint64'),
-            }[band.DataType]
+            }
+            np_dtype = np_type_map[band.DataType]
         else:
             band = None
             np_dtype = np.dtype('float64')
@@ -674,9 +683,13 @@ class LayerOperation(LayerMathMixin):
             with SharedMemoryManager() as smm:
 
                 mem_sem_cast = []
-                for i in range(worker_count):
+                for _ in range(worker_count):
                     shared_buf = smm.SharedMemory(size=np_dtype.itemsize * self.ystep * computation_window.xsize)
-                    cast_buf = np.ndarray((self.ystep, computation_window.xsize), dtype=np_dtype, buffer=shared_buf.buf)
+                    cast_buf : npt.NDArray = np.ndarray(
+                        (self.ystep, computation_window.xsize),
+                        dtype=np_dtype,
+                        buffer=shared_buf.buf
+                    )
                     cast_buf[:] = np.zeros((self.ystep, computation_window.xsize), np_dtype)
                     mem_sem_cast.append((shared_buf, Semaphore(), cast_buf))
 
@@ -746,7 +759,14 @@ class LayerOperation(LayerMathMixin):
 
         return total if and_sum else None
 
-    def parallel_save(self, destination_layer, and_sum=False, callback=None, parallelism=None, band=1):
+    def parallel_save(
+        self,
+        destination_layer,
+        and_sum=False,
+        callback=None,
+        parallelism=None,
+        band=1
+    ) -> Optional[float]:
         if destination_layer is None:
             raise ValueError("Layer is required")
         return self._parallel_save(destination_layer, and_sum, callback, parallelism, band)
@@ -754,6 +774,50 @@ class LayerOperation(LayerMathMixin):
     def parallel_sum(self, callback=None, parallelism=None, band=1):
         return self._parallel_save(None, True, callback, parallelism, band)
 
+    def to_geotiff(
+        self,
+        filename: Union[Path,str],
+        and_sum: bool = False,
+        parallelism:Optional[int]=None
+    ) -> Optional[float]:
+        """Saves a calculation to a raster file, optionally also returning the sum of pixels.
+
+        Parameters
+        ----------
+        filename : Path
+            Path of the raster to save the result to.
+        and_sum : bool, default=False
+            If true then the function will also calculate the sum of the raster as it goes and return that value.
+        parallelism : int, optional, default=None
+            If passed, attempt to use multiple CPU cores up to the number provided.
+
+        Returns
+        -------
+        float, optional
+            Either returns None, or the sum of the pixels in the resulting raster if `and_sum` was specified.
+        """
+
+        # We want to write to a tempfile before we move the result into place, but we can't use
+        # the actual $TMPDIR as that might be on a different device, and so we use a file next to where
+        # the final file will be, so we just need to rename the file at the end, not move it.
+        if isinstance(filename, str):
+            filename = Path(filename)
+        target_dir = filename.parent
+
+        with tempfile.NamedTemporaryFile(dir=target_dir, delete=False) as tempory_file:
+            # Local import due to circular dependancy
+            from yirgacheffe.layers.rasters import RasterLayer # type: ignore # pylint: disable=C0415
+            with RasterLayer.empty_raster_layer_like(self, filename=tempory_file.name) as layer:
+                if parallelism is None:
+                    result = self.save(layer, and_sum=and_sum)
+                else:
+                    result = self.parallel_save(layer, and_sum=and_sum, parallelism=parallelism)
+
+            os.makedirs(target_dir, exist_ok=True)
+            os.rename(src=tempory_file.name, dst=filename)
+
+        return result
+
 class ShaderStyleOperation(LayerOperation):
 
     def _eval(self, area, index, step, target_window=None):

yirgacheffe/window.py

@@ -1,3 +1,4 @@
+from __future__ import annotations
 import math
 import sys
 from collections import namedtuple
@@ -37,6 +38,17 @@ class Area:
     right: float
     bottom: float
 
+    @staticmethod
+    def world() -> Area:
+        """Creates an area that covers the entire planet.
+
+        Returns
+        -------
+        Area
+            An area where the extents are nan, but is_world returns true.
+        """
+        return Area(float("nan"), float("nan"), float("nan"), float("nan"))
+
     def __hash__(self):
         return (self.left, self.top, self.right, self.bottom).__hash__()
 
@@ -69,6 +81,17 @@ class Area:
             bottom=self.bottom - offset
         )
 
+    @property
+    def is_world(self) -> bool:
+        """Returns true if this is a global area, independant of projection.
+
+        Returns
+        -------
+        bool
+            True is the Area was created with `world` otherwise False.
+        """
+        return math.isnan(self.left)
+
     def overlaps(self, other) -> bool:
         """Check if this area overlaps with another area.
 
@@ -82,6 +105,10 @@ class Area:
         bool
             True if the two areas intersect, otherwise false.
         """
+
+        if self.is_world or other.is_world:
+            return True
+
         return (
             (self.left <= other.left <= self.right) or
             (self.left <= other.right <= self.right) or

{yirgacheffe-1.4.0.dist-info → yirgacheffe-1.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: yirgacheffe
-Version: 1.4.0
+Version: 1.5.0
 Summary: Abstraction of gdal datasets for doing basic math operations
 Author-email: Michael Dales <mwd24@cam.ac.uk>
 License-Expression: ISC
@@ -13,6 +13,7 @@ Requires-Dist: numpy
 Requires-Dist: gdal[numpy]
 Requires-Dist: scikit-image
 Requires-Dist: torch
+Requires-Dist: dill
 Provides-Extra: dev
 Requires-Dist: mypy; extra == "dev"
 Requires-Dist: pylint; extra == "dev"
@@ -52,12 +53,12 @@ The motivation for Yirgacheffe layers is to make working with gdal data slightly
 For example, if we wanted to do a simple [Area of Habitat](https://github.com/quantifyearth/aoh-calculator/) calculation, whereby we find the pixels where a species resides by combining its range polygon, its habitat preferences, and its elevation preferences, the code would be like this:
 
 ```python
-from yirgacheffe.layer import RasterLayer, VectorLayer
+import yirgaceffe as yg
 
-habitat_map = RasterLayer.layer_from_file("habitats.tif")
-elevation_map = RasterLayer.layer_from_file('elevation.tif')
-range_polygon = VectorLayer.layer_from_file('species123.geojson', raster_like=habitat_map)
-area_per_pixel_map = RasterLayer.layer_from_file('area_per_pixel.tif')
+habitat_map = yg.read_raster("habitats.tif")
+elevation_map = yg.read_raster('elevation.tif')
+range_polygon = yg.read_shape_like('species123.geojson', like=habitat_map)
+area_per_pixel_map = yg.read_raster('area_per_pixel.tif')
 
 refined_habitat = habitat_map.isin([...species habitat codes...])
 refined_elevation = (elevation_map >= species_min) && (elevation_map <= species_max)
@@ -70,8 +71,8 @@ print(f'area for species 123: {aoh.sum()}')
 Similarly, you could save the result to a new raster layer:
 
 ```python
-with RasterLayer.empty_raster_layer_like(aoh, filename="result.tif") as result:
-    aoh.save(result)
+    ...
+    aoh.to_geotiff("result.tif")
 ```
 
 Yirgacheffe will automatically infer if you want to do an intersection of maps or a union of the maps based on the operators you use (see below for a full table). You can explicitly override that if you want.
@@ -109,27 +110,28 @@ If you have set either the intersection window or union window on a layer and yo
 If doing per-layer operations isn't applicable for your application, you can read the pixel values for all layers (including VectorLayers) by calling `read_array` similarly to how you would for gdal. The data you access will be relative to the specified window - that is, if you've called either `set_window_for_intersection` or `set_window_for_union` then `read_array` will be relative to that and Yirgacheffe will clip or expand the data with zero values as necessary.
 
 
-### Todo but not supported
-
-Yirgacheffe is work in progress, so things planned but not supported currently:
-
-* Dynamic pixel scale adjustment - all raster layers must be provided at the same pixel scale currently  *NOW IN EXPERIMENTAL TESTING, SEE BELOW*
-* A fold operation
-* CUDA/Metal support via CUPY/MLX
-* Dispatching work across multiple CPUs *NOW IN EXPERIMENTAL TESTING, SEE BELOW*
-
-
-
 ## Layer types
 
+Note that as part of the move to the next major release, 2.0, we are adding simpler ways to create layers. Not all of those have been implemented yet, which is why this section has some inconsistencies. However, given many of the common cases are already covered, we present the new 2.0 style methods (`read_raster` and similar) here so you can write cleaner code today rather than making people wait for the final 2.0 release.
+
 ### RasterLayer
 
 This is your basic GDAL raster layer, which you load from a geotiff.
 
 ```python
+from yirgaceffe.layers import RasterLayer
+
 with RasterLayer.layer_from_file('test1.tif') as layer:
-    data = layer.read_array(0, 0, 10, 10)
-    ...
+    total = layer.sum()
+```
+
+The new 2.0 way of doing this is:
+
+```python
+import yirgacheffe as yg
+
+with yg.read_raster('test.tif') as layer:
+    total = layer.sum()
 ```
 
 You can also create empty layers ready for you to store results, either by taking the dimensions from an existing layer. In both these cases you can either provide a filename to which the data will be written, or if you do not provide a filename then the layer will only exist in memory - this will be more efficient if the layer is being used for intermediary results.
@@ -166,51 +168,30 @@ This layer will load vector data and rasterize it on demand as part of a calcula
 Because it will be rasterized you need to specify the pixel scale and map projection to be used when rasterising the data, and the common way to do that is by using one of your other layers.
 
 ```python
-with VectorLayer.layer_from_file('range.gpkg', 'id_no == 42', layer1.pixel_scale, layer1.projection) as layer:
-    ...
-```
-
-This class was formerly called `DynamicVectorRangeLayer`, a name now deprecated.
-
+from yirgaceffe import WGS_84_PROJECTION
+from yirgaceffe.window import PixelScale
+from yirgaceffe.layers import VectorLayer
 
-### UniformAreaLayer
-
-In certain calculations you find you have a layer where all the rows of data are the same - notably geotiffs that contain the area of a given pixel do this due to how conventional map projections work. It's hugely inefficient to load the full map into memory, so whilst you could just load them as `Layer` types, we recommend you do:
-
-```python
-with UniformAreaLayer('area.tiff') as layer:
-    ....
+with VectorLayer.layer_from_file('range.gpkg', PixelScale(0.001, -0.001), WGS_84_PROJECTION) as layer:
+    ...
 ```
 
-Note that loading this data can still be very slow, due to how image compression works. So if you plan to use area.tiff more than once, we recommend use save an optimised version - this will do the slow uncompression once and then save a minimal file to speed up future processing:
+The new 2.0 way of doing this is:
 
 ```python
-if not os.path.exists('yirgacheffe_area.tiff'):
-    UniformAreaLayer.generate_narrow_area_projection('area.tiff', 'yirgacheffe_area.tiff')
-area_layer = UniformAreaLayer('yirgacheffe_area.tiff')
-```
-
-
-### ConstantLayer
+import yirgacheffe as yg
 
-This is there to simplify code when you have some optional layers. Rather than littering your code with checks, you can just use a constant layer, which can be included in calculations and will just return an fixed value as if it wasn't there. Useful with 0.0 or 1.0 for sum or multiplication null layers.
-
-```python
-try:
-    area_layer = UniformAreaLayer('myarea.tiff')
-except FileDoesNotExist:
-    area_layer = ConstantLayer(0.0)
+with yg.read_shape('range.gpkg', (0.001, -0.001), WGS_84_PROJECTION) as layer:
+    ...
 ```
 
+It is more common that when a shape file is loaded that its pixel size and projection will want to be made to match that of an existing raster (as per the opening area of habitat example). For that there is the following convenience method:
 
-### H3CellLayer
-
-If you have H3 installed, you can generate a mask layer based on an H3 cell identifier, where pixels inside the cell will have a value of 1, and those outside will have a value of 0.
-
-Becuase it will be rasterized you need to specify the pixel scale and map projection to be used when rasterising the data, and the common way to do that is by using one of your other layers.
 
 ```python
-hex_cell_layer = H3CellLayer('88972eac11fffff', layer1.pixel_scale, layer1.projection)
+with yg.read_raster("test.tif") as raster_layer:
+    with yg.read_shape_like('range.gpkg', raster_layer) as shape_layer:
+        ...
 ```
 
 ### GroupLayer
@@ -239,6 +220,15 @@ with GroupLayer.layer_from_directory('.') as all_tiles:
     ...
 ```
 
+The new 2.0 way of doing this is:
+
+```python
+import yirgacheffe as yg
+
+with yg.read_rasters(['tile_N10_E10.tif', 'tile_N20_E10.tif']) as all_tiles:
+    ...
+```
+
 ### TiledGroupLayer
 
 This is a specialisation of GroupLayer, which you can use if your layers are all the same size and form a grid, as is often the case with map tiles. In this case the rendering code can be optimised and this class is significantly faster that GroupLayer.
@@ -249,11 +239,59 @@ tile2 = RasterLayer.layer_from_file('tile_N20_E10.tif')
 all_tiles = TiledGroupLayer([tile1, tile2])
 ```
 
+The new 2.0 way of doing this is:
+
+```python
+import yirgacheffe as yg
+
+with yg.read_rasters(['tile_N10_E10.tif', 'tile_N20_E10.tif'], tiled=True) as all_tiles:
+    ...
+```
+
 Notes:
 
 * You can have missing tiles, and these will be filled in with zeros.
 * You can have tiles that overlap, so long as they still conform to the rule that all tiles are the same size and on a grid.
 
+### ConstantLayer
+
+This is there to simplify code when you have some optional layers. Rather than littering your code with checks, you can just use a constant layer, which can be included in calculations and will just return an fixed value as if it wasn't there. Useful with 0.0 or 1.0 for sum or multiplication null layers.
+
+```python
+try:
+    area_layer = RasterLayer.layer_from_file('myarea.tiff')
+except FileDoesNotExist:
+    area_layer = ConstantLayer(0.0)
+```
+
+### H3CellLayer
+
+If you have H3 installed, you can generate a mask layer based on an H3 cell identifier, where pixels inside the cell will have a value of 1, and those outside will have a value of 0.
+
+Becuase it will be rasterized you need to specify the pixel scale and map projection to be used when rasterising the data, and the common way to do that is by using one of your other layers.
+
+```python
+hex_cell_layer = H3CellLayer('88972eac11fffff', layer1.pixel_scale, layer1.projection)
+```
+
+
+### UniformAreaLayer
+
+In certain calculations you find you have a layer where all the rows of data are the same - notably geotiffs that contain the area of a given pixel do this due to how conventional map projections work. It's hugely inefficient to load the full map into memory, so whilst you could just load them as `Layer` types, we recommend you do:
+
+```python
+with UniformAreaLayer('area.tiff') as layer:
+    ....
+```
+
+Note that loading this data can still be very slow, due to how image compression works. So if you plan to use area.tiff more than once, we recommend use save an optimised version - this will do the slow uncompression once and then save a minimal file to speed up future processing:
+
+```python
+if not os.path.exists('yirgacheffe_area.tiff'):
+    UniformAreaLayer.generate_narrow_area_projection('area.tiff', 'yirgacheffe_area.tiff')
+area_layer = UniformAreaLayer('yirgacheffe_area.tiff')
+```
+
 
 ## Supported operations on layers
 
@@ -280,6 +318,24 @@ with RasterLayer.layer_from_file('test1.tif') as layer1:
         calc.save(result)
 ```
 
+
+The new 2.0 way of doing these are:
+
+```python
+with yg.read_raster('test1.tif') as layer1:
+    with yg.read_raster('test2.tif') as layer2:
+        result = layer1 + layer2
+        result.to_geotiff("result.tif")
+```
+
+or
+
+```python
+with yg.read_raster('test1.tif') as layer1:
+    result = layer1 * 42.0
+    result.to_geotiff("result.tif")
+```
+
 ### Boolean testing
 
 Testing for equality, less than, less than or equal, greater than, and greater than or equal are supported on layers, along with logical or and logical and, as per this example, where `elevation_upper` and `elevation_lower` are scalar values:

yirgacheffe-1.5.0.dist-info/RECORD

@@ -0,0 +1,25 @@
+yirgacheffe/__init__.py,sha256=n0v998xPOMMS6hdAQ16UNzmJUdnN5612HRtdudwjYa4,302
+yirgacheffe/_core.py,sha256=6g_gqTBj4XdJ8TOiMPos5asLOWwSeKqIhpvYP49RgtI,3916
+yirgacheffe/constants.py,sha256=uCWJwec3-ND-zVxYbsk1sdHKANl3ToNCTPg7MZb0j2g,434
+yirgacheffe/operators.py,sha256=cEgnngjj_fZOg9BileC7WTp6VP9TnmKibR84pDK7A8I,31362
+yirgacheffe/rounding.py,sha256=ggBG4lMyLMtHLW3dBxr3gBCcF2qhRrY5etZiFGlIoqA,2258
+yirgacheffe/window.py,sha256=kR8sHQ6lcixpndOWC18wLRgbgS8y00tq4Fkh8PLESvM,8209
+yirgacheffe/_backends/__init__.py,sha256=jN-2iRrHStnPI6cNL7XhwhsROtI0EaGfIrbF5c-ECV0,334
+yirgacheffe/_backends/enumeration.py,sha256=pADawllxpW_hW-IVVvZpHWIKzvEMs9aaqfkZRD1zjnY,1003
+yirgacheffe/_backends/mlx.py,sha256=2vOTMqHbQbeqt81Eq_8hxWDXZHaPsDpbXkALRVGEnnw,6130
+yirgacheffe/_backends/numpy.py,sha256=cYO628s4-5K_-Bp3CrnHegzYSZfkt2QC8iE9oOOMtvA,4069
+yirgacheffe/layers/__init__.py,sha256=mYKjw5YTcMNv_hMy7a6K4yRzIuNUbR8WuBTw4WIAmSk,435
+yirgacheffe/layers/area.py,sha256=yIRXzeeLi3MMyuh4LG_VgZrKNWe5xwZgDGdgaoYRpP0,3805
+yirgacheffe/layers/base.py,sha256=1B3s4cyC-DBeM357U9ds4mqwE23iIiD8x5F4aVEfc_c,12057
+yirgacheffe/layers/constant.py,sha256=c3ugo58jkzImCiEqpzJoGLuBKJPGHRni1kxnKKcZs2E,1328
+yirgacheffe/layers/group.py,sha256=5TICz6bQREzah1MdcEttYbTIOk0zX-KCqyuuVdaz7HU,15472
+yirgacheffe/layers/h3layer.py,sha256=kWDqs6fIkHLR7gDL2E6F5y9-XxT6ws4M3Tj_7qF090U,9863
+yirgacheffe/layers/rasters.py,sha256=nJKgvDpPEbj_7dG55SLGFBqPGMXjkR2oGWIRne0b558,12682
+yirgacheffe/layers/rescaled.py,sha256=W-AhFuTIYAJVgMvcLHAZdrFwUxuJuVnAQWv8d4x1mDM,3048
+yirgacheffe/layers/vectors.py,sha256=Y7zQkbNWYY9iNyIxfE0iN3BeWJt8yPgfSOcWbR1JDKM,15781
+yirgacheffe-1.5.0.dist-info/licenses/LICENSE,sha256=dNSHwUCJr6axStTKDEdnJtfmDdFqlE3h1NPCveqPfnY,757
+yirgacheffe-1.5.0.dist-info/METADATA,sha256=zjsKlcKx50LdA4D2eIdHw17E4Zl4nH9ldVSS6eS1TPc,21842
+yirgacheffe-1.5.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+yirgacheffe-1.5.0.dist-info/entry_points.txt,sha256=j4KgHXbVGbGyfTySc1ypBdERpfihO4WNjppvCdE9HjE,52
+yirgacheffe-1.5.0.dist-info/top_level.txt,sha256=9DBFlKO2Ld3hG6TuE3qOTd3Tt8ugTiXil4AN4Wr9_y0,12
+yirgacheffe-1.5.0.dist-info/RECORD,,

yirgacheffe-1.4.0.dist-info/RECORD

@@ -1,24 +0,0 @@
-yirgacheffe/__init__.py,sha256=nrVZPE_4DgReqmqEOfUaXJiRtxjOt-OJSIVi51Z5k98,587
-yirgacheffe/constants.py,sha256=WccPcISG1FqL_Kw1tI72BJGjHy6RvEcGEx_I9RK776U,42
-yirgacheffe/operators.py,sha256=eeDlIGFrspHqQBWdcXVjbP2mBEDsPxhXZucWo74geTc,29343
-yirgacheffe/rounding.py,sha256=ggBG4lMyLMtHLW3dBxr3gBCcF2qhRrY5etZiFGlIoqA,2258
-yirgacheffe/window.py,sha256=PVh9EIg1PMcUENjC2yahmrolGWaJP4OeM44uKqQ6I0U,7504
-yirgacheffe/_backends/__init__.py,sha256=jN-2iRrHStnPI6cNL7XhwhsROtI0EaGfIrbF5c-ECV0,334
-yirgacheffe/_backends/enumeration.py,sha256=pADawllxpW_hW-IVVvZpHWIKzvEMs9aaqfkZRD1zjnY,1003
-yirgacheffe/_backends/mlx.py,sha256=oIWJULZ9NBPTqydnCTQxVwbfmBjQPOsKvY9Rhr6_wl8,6076
-yirgacheffe/_backends/numpy.py,sha256=qQYvff1oHIuGUimV04rcFyPxnwEf0acvVd3ijeom4T4,4015
-yirgacheffe/layers/__init__.py,sha256=mYKjw5YTcMNv_hMy7a6K4yRzIuNUbR8WuBTw4WIAmSk,435
-yirgacheffe/layers/area.py,sha256=yIRXzeeLi3MMyuh4LG_VgZrKNWe5xwZgDGdgaoYRpP0,3805
-yirgacheffe/layers/base.py,sha256=l2spGsDsv2DaUqkK-nuJCC97fw0kVWaLntvvLqZgJS4,11959
-yirgacheffe/layers/constant.py,sha256=LWQuGGuUkJirLoQomZHs44oksmMKcvNGM8pOuRk9vHo,1427
-yirgacheffe/layers/group.py,sha256=Fys5BvYmWRQMc95YE8Gy6bxxZRqvHUU7gILFE_X-CpY,15330
-yirgacheffe/layers/h3layer.py,sha256=kWDqs6fIkHLR7gDL2E6F5y9-XxT6ws4M3Tj_7qF090U,9863
-yirgacheffe/layers/rasters.py,sha256=I9bRuqb0W8EEvdSq3rAeKNmezIRK-yajFaHtDFR81sw,12630
-yirgacheffe/layers/rescaled.py,sha256=v3ZXo3aNNDP4b8O6QnQHgrhBu0GslTgiZQmy6O8vb8k,3004
-yirgacheffe/layers/vectors.py,sha256=3QWjg0E9deZyLIBp-BewgDGY90Ufqd6OcUA7jzJXJPo,15515
-yirgacheffe-1.4.0.dist-info/licenses/LICENSE,sha256=dNSHwUCJr6axStTKDEdnJtfmDdFqlE3h1NPCveqPfnY,757
-yirgacheffe-1.4.0.dist-info/METADATA,sha256=XamBMRPMRWZvzTu4yXqyhYIdlQkJV8mb5qCIAnt06Ls,20496
-yirgacheffe-1.4.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-yirgacheffe-1.4.0.dist-info/entry_points.txt,sha256=j4KgHXbVGbGyfTySc1ypBdERpfihO4WNjppvCdE9HjE,52
-yirgacheffe-1.4.0.dist-info/top_level.txt,sha256=9DBFlKO2Ld3hG6TuE3qOTd3Tt8ugTiXil4AN4Wr9_y0,12
-yirgacheffe-1.4.0.dist-info/RECORD,,