yirgacheffe 1.4.1__py3-none-any.whl → 1.6.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/_core.py

@@ -0,0 +1,136 @@
+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,
+    ignore_nodata: bool = False,
+) -> 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)
+    ignore_nodata : bool, default=False
+        If the GeoTIFF has a NODATA value, don't subsitute that value for NaN
+
+    Returns
+    -------
+    RasterLayer
+        Returns an layer representing the raster data.
+    """
+    return RasterLayer.layer_from_file(filename, band, ignore_nodata)
+
+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/area.py

@@ -56,12 +56,12 @@ class UniformAreaLayer(RasterLayer):
                 return False
         return True
 
-    def __init__(self, dataset, name: Optional[str] = None, band: int = 1):
+    def __init__(self, dataset, name: Optional[str] = None, band: int = 1, ignore_nodata: bool = False):
         if dataset.RasterXSize > 1:
             raise ValueError("Expected a shrunk dataset")
         self.databand = dataset.GetRasterBand(1).ReadAsArray(0, 0, 1, dataset.RasterYSize)
 
-        super().__init__(dataset, name, band)
+        super().__init__(dataset, name, band, ignore_nodata)
 
         transform = dataset.GetGeoTransform()
 
@@ -84,7 +84,14 @@ class UniformAreaLayer(RasterLayer):
         )
         self._raster_xsize = self.window.xsize
 
-    def read_array_with_window(self, xoffset: int, yoffset: int, xsize: int, ysize: int, window: Window) -> Any:
+    def _read_array_with_window(
+        self,
+        xoffset: int,
+        yoffset: int,
+        xsize: int,
+        ysize: int,
+        window: Window,
+    ) -> Any:
         if ysize <= 0:
             raise ValueError("Request dimensions must be positive and non-zero")
         offset = window.yoff + yoffset

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
@@ -66,8 +66,12 @@ class YirgacheffeLayer(LayerMathMixin):
             raise AttributeError("Layer has no window")
         return self._window
 
+    @property
+    def nodata(self) -> None:
+        return None
+
     @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 +91,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 +187,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 +198,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
@@ -227,10 +231,24 @@ class YirgacheffeLayer(LayerMathMixin):
         self._window = new_window
         self._active_area = new_area
 
-    def read_array_with_window(self, _x: int, _y: int, _xsize: int, _ysize: int, window: Window) -> Any:
+    def _read_array_with_window(
+        self,
+        _x: int,
+        _y: int,
+        _xsize: int,
+        _ysize: int,
+        _window: Window,
+    ) -> Any:
         raise NotImplementedError("Must be overridden by subclass")
 
-    def read_array_for_area(self, target_area: Area, x: int, y: int, width: int, height: int) -> Any:
+    def _read_array_for_area(
+        self,
+        target_area: Area,
+        x: int,
+        y: int,
+        width: int,
+        height: int,
+    ) -> Any:
         assert self._pixel_scale is not None
 
         target_window = Window(
@@ -247,10 +265,28 @@ class YirgacheffeLayer(LayerMathMixin):
                 (self._pixel_scale.ystep * -1.0)
             ),
         )
-        return self.read_array_with_window(x, y, width, height, target_window)
+        return self._read_array_with_window(x, y, width, height, target_window)
 
     def read_array(self, x: int, y: int, width: int, height: int) -> Any:
-        return self.read_array_with_window(x, y, width, height, self.window)
+        """Reads data from the layer based on the current reference window.
+
+        Arguments
+        ---------
+        x : int
+            X axis offset for reading
+        y : int
+            Y axis offset for reading
+        width : int
+            Width of data to read
+        height : int
+            Height of data to read
+
+        Results
+        -------
+        Any
+            An array of values from the layer.
+        """
+        return self._read_array_with_window(x, y, width, height, self.window)
 
     def latlng_for_pixel(self, x_coord: int, y_coord: int) -> Tuple[float,float]:
         """Get geo coords for pixel. This is relative to the set view window."""

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)
 
@@ -33,8 +28,22 @@ class ConstantLayer(YirgacheffeLayer):
     def read_array(self, _x: int, _y: int, width: int, height: int) -> Any:
         return backend.full((height, width), self.value)
 
-    def read_array_with_window(self, _x: int, _y: int, width: int, height: int, _window: Window) -> Any:
+    def _read_array_with_window(
+        self,
+        _x: int,
+        _y: int,
+        width: int,
+        height: int,
+        _window: Window,
+    ) -> Any:
         return backend.full((height, width), self.value)
 
-    def read_array_for_area(self, _target_area: Area, x: int, y: int, width: int, height: int) -> Any:
+    def _read_array_for_area(
+        self,
+        _target_area: Area,
+        x: int,
+        y: int,
+        width: int,
+        height: int,
+    ) -> Any:
         return self.read_array(x, y, width, height)

yirgacheffe/layers/group.py

@@ -1,12 +1,12 @@
 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
+from numpy import ma
 
+from ..operators import DataType
 from ..rounding import are_pixel_scales_equal_enough, round_down_pixels
 from ..window import Area, Window
 from .base import YirgacheffeLayer
@@ -23,19 +23,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 +49,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]):
@@ -95,8 +105,14 @@ class GroupLayer(YirgacheffeLayer):
         except AttributeError:
             pass # called from Base constructor before we've added the extra field
 
-    def read_array_with_window(self, xoffset: int, yoffset: int, xsize: int, ysize: int, window: Window) -> Any:
-
+    def _read_array_with_window(
+        self,
+        xoffset: int,
+        yoffset: int,
+        xsize: int,
+        ysize: int,
+        window: Window,
+    ) -> Any:
         if (xsize <= 0) or (ysize <= 0):
             raise ValueError("Request dimensions must be positive and non-zero")
 
@@ -130,12 +146,15 @@ class GroupLayer(YirgacheffeLayer):
         if len(contributing_layers) == 1:
             layer, adjusted_layer_window, intersection = contributing_layers[0]
             if target_window == intersection:
-                return layer.read_array(
+                data = layer.read_array(
                     intersection.xoff - adjusted_layer_window.xoff,
                     intersection.yoff - adjusted_layer_window.yoff,
                     intersection.xsize,
                     intersection.ysize
                 )
+                if layer.nodata is not None:
+                    data[data.isnan()] = 0.0
+                return data
 
         result = np.zeros((ysize, xsize), dtype=float)
         for layer, adjusted_layer_window, intersection in contributing_layers:
@@ -143,14 +162,26 @@ class GroupLayer(YirgacheffeLayer):
                 intersection.xoff - adjusted_layer_window.xoff,
                 intersection.yoff - adjusted_layer_window.yoff,
                 intersection.xsize,
-                intersection.ysize
+                intersection.ysize,
             )
             result_x_offset = (intersection.xoff - xoffset) - window.xoff
             result_y_offset = (intersection.yoff - yoffset) - window.yoff
-            result[
-                result_y_offset:result_y_offset + intersection.ysize,
-                result_x_offset:result_x_offset + intersection.xsize
-            ] = data
+            if layer.nodata is None:
+                result[
+                    result_y_offset:result_y_offset + intersection.ysize,
+                    result_x_offset:result_x_offset + intersection.xsize
+                ] = data
+            else:
+                masked = ma.masked_invalid(data)
+                before = result[
+                    result_y_offset:result_y_offset + intersection.ysize,
+                    result_x_offset:result_x_offset + intersection.xsize
+                ]
+                merged = ma.where(masked.mask, before, masked)
+                result[
+                    result_y_offset:result_y_offset + intersection.ysize,
+                    result_x_offset:result_x_offset + intersection.xsize
+                ] = merged
 
         return backend.promote(result)
 
@@ -205,7 +236,14 @@ class TiledGroupLayer(GroupLayer):
     * You can have missing tiles, and it'll fill in zeros.
     * The tiles can overlap - e.g., JRC Annual Change tiles all overlap by a few pixels on all edges.
     """
-    def read_array_with_window(self, xoffset: int, yoffset: int, xsize: int, ysize: int, window: Window) -> Any:
+    def _read_array_with_window(
+        self,
+        xoffset: int,
+        yoffset: int,
+        xsize: int,
+        ysize: int,
+        window: Window,
+    ) -> Any:
         if (xsize <= 0) or (ysize <= 0):
             raise ValueError("Request dimensions must be positive and non-zero")
 

yirgacheffe/layers/h3layer.py

@@ -82,7 +82,14 @@ class H3CellLayer(YirgacheffeLayer):
     def datatype(self) -> DataType:
         return DataType.Float64
 
-    def read_array_with_window(self, xoffset: int, yoffset: int, xsize: int, ysize: int, window: Window) -> Any:
+    def _read_array_with_window(
+        self,
+        xoffset: int,
+        yoffset: int,
+        xsize: int,
+        ysize: int,
+        window: Window,
+    ) -> Any:
         assert self._pixel_scale is not None
 
         if (xsize <= 0) or (ysize <= 0):

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,12 @@ 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,
+        ignore_nodata: bool = False,
+    ) -> RasterLayer:
         try:
             dataset = gdal.Open(filename, gdal.GA_ReadOnly)
         except RuntimeError as exc:
@@ -224,9 +229,15 @@ class RasterLayer(YirgacheffeLayer):
             _ = dataset.GetRasterBand(band)
         except RuntimeError as exc:
             raise InvalidRasterBand(band) from exc
-        return cls(dataset, filename, band)
-
-    def __init__(self, dataset: gdal.Dataset, name: Optional[str] = None, band: int = 1):
+        return cls(dataset, str(filename), band, ignore_nodata)
+
+    def __init__(
+        self,
+        dataset: gdal.Dataset,
+        name: Optional[str] = None,
+        band: int = 1,
+        ignore_nodata: bool = False,
+    ) -> None:
         if not dataset:
             raise ValueError("None is not a valid dataset")
 
@@ -252,10 +263,11 @@ 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
+        self._ignore_nodata = ignore_nodata
 
     @property
     def _raster_dimensions(self) -> Tuple[int,int]:
@@ -275,7 +287,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()
@@ -305,7 +317,21 @@ class RasterLayer(YirgacheffeLayer):
         assert self._dataset
         return DataType.of_gdal(self._dataset.GetRasterBand(1).DataType)
 
-    def read_array_with_window(self, xoffset: int, yoffset: int, xsize: int, ysize: int, window: Window) -> Any:
+    @property
+    def nodata(self) -> Optional[Any]:
+        if self._dataset is None:
+            self._unpark()
+        assert self._dataset
+        return self._dataset.GetRasterBand(self._band).GetNoDataValue()
+
+    def _read_array_with_window(
+        self,
+        xoffset: int,
+        yoffset: int,
+        xsize: int,
+        ysize: int,
+        window: Window,
+    ) -> Any:
         if self._dataset is None:
             self._unpark()
         assert self._dataset
@@ -335,7 +361,6 @@ class RasterLayer(YirgacheffeLayer):
         if target_window == intersection:
             # The target window is a subset of or equal to the source, so we can just ask for the data
             data = backend.promote(self._dataset.GetRasterBand(self._band).ReadAsArray(*intersection.as_array_args))
-            return data
         else:
             # We should read the intersection from the array, and the rest should be zeros
             subset = backend.promote(self._dataset.GetRasterBand(self._band).ReadAsArray(*intersection.as_array_args))
@@ -350,4 +375,9 @@ class RasterLayer(YirgacheffeLayer):
                 )
             )).astype(int)
             data = backend.pad(subset, region, mode='constant')
-            return data
+
+        nodata = self.nodata
+        if not self._ignore_nodata and nodata is not None:
+            data = backend.where(data == nodata, float("nan"), data)
+
+        return data

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,
@@ -61,7 +62,14 @@ class RescaledRasterLayer(YirgacheffeLayer):
     def datatype(self) -> DataType:
         return self._src.datatype
 
-    def read_array_with_window(self, xoffset: int, yoffset: int, xsize: int, ysize: int, window: Window) -> Any:
+    def _read_array_with_window(
+        self,
+        xoffset: int,
+        yoffset: int,
+        xsize: int,
+        ysize: int,
+        window: Window,
+    ) -> Any:
 
         # to avoid aliasing issues, we try to scale to the nearest pixel
         # and recrop when scaling bigger