feat: improve maskCover (#349)

geetools/Image.py

@@ -1,6 +1,8 @@
 """Toolbox for the ``ee.Image`` class."""
 from __future__ import annotations
 
+from typing import Optional
+
 import ee
 import ee_extra
 import ee_extra.Algorithms.core
@@ -1316,11 +1318,28 @@ def distance(self, other: ee.image) -> ee.Image:
 
         return ee.Image(distance)
 
-    def maskCover(self) -> ee.Image:
-        """return an image with the mask cover ratio as an image property.
+    def maskCoverRegion(
+        self,
+        region: ee.Geometry,
+        scale: Optional[int | ee.Number] = None,
+        band: Optional[str | ee.String] = None,
+        proxyValue: int | ee.Number = -999,
+        **kwargs,
+    ) -> ee.Number:
+        """Compute the coverage of masked pixels inside a Geometry.
+
+        Parameters:
+            region: The region to compute the mask coverage.
+            scale: The scale of the computation. In case you need a rough estimation use a higher scale than the original from the image.
+            band: The band to use. Defaults to the first band.
+            proxyValue: the value to use for counting the mask and avoid confusing 0s to masked values. In most cases the user should not change this value, but in case of conflicts, choose a value that is out of the range of the image values.
+
+        Kwargs:
+            maxPixels: The maximum number of pixels to reduce.
+            tileScale: A scaling factor between 0.1 and 16 used to adjust aggregation tile size; setting a larger tileScale (e.g., 2 or 4) uses smaller tiles and may enable computations that run out of memory with the default.
 
         Returns:
-            The image with the mask cover ratio as an image property.
+            The percentage of masked pixels within the region
 
         Examples:
             .. code-block:: python
@@ -1330,23 +1349,122 @@ def maskCover(self) -> ee.Image:
                     ee.Initialize()
 
                     image = ee.Image('COPERNICUS/S2_SR/20190828T151811_20190828T151809_T18GYT')
-                    image = image.maskCover()
+                    aoi = ee.Geometry.Point([11.880190936531116, 42.0159494554553]).buffer(2000)
+                    image = image.maskCoverRegion(aoi)
         """
         # compute the mask cover
-        mask, geometry = self._obj.select(0).mask(), self._obj.geometry()
-        cover = mask.reduceRegion(ee.Reducer.frequencyHistogram(), geometry, bestEffort=True)
-
+        image = self._obj.select(band or 0)
+        scale = scale or image.projection().nominalScale()
+        unmasked = image.unmask(proxyValue)
+        mask = unmasked.eq(proxyValue)
+        cover = mask.reduceRegion(
+            ee.Reducer.frequencyHistogram(), region, scale=scale, bestEffort=True, **kwargs
+        )
         # The cover result is a dictionary with each band as key (in our case the first one).
         # For each band key the number of 0 and 1 is stored in a dictionary.
         # We need to extract the number of 1 and 0 to compute the ratio which implys lots of casting.
-        values = ee.Dictionary(cover.values().get(0)).values()
-        zeros, ones = ee.Number(values.get(0)), ee.Number(values.get(1))
-        ratio = zeros.divide(zeros.add(ones))
+        values = ee.Dictionary(cover.values().get(0))
+        zeros, ones = ee.Number(values.get("0", 0)), ee.Number(values.get("1", 0))
+        ratio = ones.divide(zeros.add(ones)).multiply(100)
+
+        # we want to display this result as a 1 digit float
+        return ratio
+
+    def maskCoverRegions(
+        self,
+        collection: ee.FeatureCollection,
+        scale: Optional[int | ee.Number] = None,
+        band: Optional[str | ee.String] = None,
+        proxyValue: int | ee.Number = -999,
+        columnName: str | ee.String = "mask_cover",
+        **kwargs,
+    ) -> ee.FeatureCollection:
+        """Compute the coverage of masked pixels inside a Geometry.
+
+        Parameters:
+            collection: The collection to compute the mask coverage (in each Feature).
+            scale: The scale of the computation. In case you need a rough estimation use a higher scale than the original from the image.
+            band: The band to use. Defaults to the first band.
+            proxyValue: the value to use for counting the mask and avoid confusing 0s to masked values. In most cases the user should not change this value, but in case of conflicts, choose a value that is out of the range of the image values.
+            columnName: name of the column that will hold the value.
+
+        Kwargs:
+            tileScale: A scaling factor between 0.1 and 16 used to adjust aggregation tile size; setting a larger tileScale (e.g., 2 or 4) uses smaller tiles and may enable computations that run out of memory with the default.
+
+        Returns:
+            The passed table with the new column containing the percentage of masked pixels within the region
+
+        Examples:
+            .. code-block:: python
+
+                    import ee, geetools
+
+                    ee.Initialize()
 
-        # we want to display this resutl as a 1 digit float
-        ratio = ratio.multiply(1000).toInt().divide(10)
+                    image = ee.Image('COPERNICUS/S2_SR/20190828T151811_20190828T151809_T18GYT')
+                    reg = ee.Geometry.Point([11.880190936531116, 42.0159494554553]).buffer(2000)
+                    aoi = ee.FeatureCollection([ee.Feature(reg)])
+                    image = image.maskCoverRegions(aoi)
+        """
+        # compute the mask cover
+        properties = collection.propertyNames()  # original properties
+        image = self._obj.select(band or 0)
+        scale = scale or image.projection().nominalScale()
+        unmasked = image.unmask(proxyValue)
+        mask = unmasked.eq(proxyValue)
+        column = "_geetools_histo_"
+        cover = mask.reduceRegions(
+            collection=collection,
+            reducer=ee.Reducer.frequencyHistogram().setOutputs([column]),
+            scale=scale,
+            **kwargs,
+        )
+
+        def compute_percentage(feat: ee.Feature) -> ee.Feature:
+            histo = ee.Dictionary(feat.get(column))
+            zeros, ones = ee.Number(histo.get("0", 0)), ee.Number(histo.get("1", 0))
+            ratio = ones.divide(zeros.add(ones)).multiply(100)
+            return feat.select(properties).set(columnName, ratio)
+
+        return cover.map(compute_percentage)
+
+    def maskCover(
+        self,
+        scale: Optional[int] = None,
+        proxyValue: int = -999,
+        propertyName: str = "mask_cover",
+        **kwargs,
+    ) -> ee.Image:
+        """Compute the percentage of masked pixels inside the image.
+
+        It will use the geometry and the first band of the image.
+
+        Parameters:
+            scale: The scale of the computation. In case you need a rough estimation use a higher scale than the original from the image.
+            proxyValue: the value to use for counting the mask and avoid confusing 0s to masked values. Choose a value that is out of the range of the image values.
+            propertyName: the name of the property where the value will be saved
+
+        Kwargs:
+            maxPixels: The maximum number of pixels to reduce.
+            tileScale: A scaling factor between 0.1 and 16 used to adjust aggregation tile size; setting a larger tileScale (e.g., 2 or 4) uses smaller tiles and may enable computations that run out of memory with the default.
+
+        Returns:
+            The same image with the percentage of masked pixels as a property
+
+        Examples:
+            .. code-block:: python
 
-        return ee.Image(self._obj.set("mask_cover", ratio))
+                    import ee, geetools
+
+                    ee.Initialize()
+
+                    image = ee.Image('COPERNICUS/S2_SR/20190828T151811_20190828T151809_T18GYT')
+                    aoi = ee.Geometry.Point([11.880190936531116, 42.0159494554553]).buffer(2000)
+                    image = image.maskCoverRegion(aoi)
+        """
+        region = self._obj.geometry()
+        value = self.maskCoverRegion(region, scale, None, proxyValue, **kwargs)
+        return self._obj.set(propertyName, value)
 
     def plot(
         self,

tests/test_Image.py

@@ -570,20 +570,46 @@ def other(self):
 
 
 class TestMaskCover:
-    """Test the ``maskCover`` method."""
-
-    def test_mask_cover(self):
-        image = self.image.geetools.maskCover()
-        assert isclose(image.get("mask_cover").getInfo(), 99.2)
+    """Test the ``maskCoverRegion`` method."""
+
+    def test_mask_cover_region(self):
+        aoi = ee.Geometry.Point([12.210900891755129, 41.928551351175386]).buffer(2200)
+        ratio = self.image.geetools.maskCoverRegion(aoi, scale=10)
+        assert isclose(ratio.getInfo(), 9.99, abs_tol=0.01)
+
+    def test_mask_cover_region_zero(self):
+        aoi = ee.Geometry.Point([11.880190936531116, 42.0159494554553]).buffer(1000)
+        ratio = self.image.geetools.maskCoverRegion(aoi, scale=10)
+        assert isclose(ratio.getInfo(), 0)
+
+    def test_mask_cover_regions(self):
+        geom = ee.Geometry.Point([12.210900891755129, 41.928551351175386]).buffer(2200)
+        aoi = ee.FeatureCollection([ee.Feature(geom, {"test_property": 1})])
+        result = self.image.geetools.maskCoverRegions(aoi, scale=10)
+        feat = ee.Feature(result.first())
+        ratio = feat.getInfo()["properties"]["mask_cover"]
+        # ratio = ee.Number(feat.get('mask_cover'))
+        # the last line should work, but it doesn't, I don't know why
+        assert isclose(ratio, 9.99, abs_tol=0.01)
+
+    def test_mask_cover_regions_zero(self):
+        geom = ee.Geometry.Point([11.880190936531116, 42.0159494554553]).buffer(1000)
+        aoi = ee.FeatureCollection([ee.Feature(geom, {"test_property": 1})])
+        result = self.image.geetools.maskCoverRegions(aoi, scale=10)
+        feat = ee.Feature(result.first())
+        ratio = feat.getInfo()["properties"]["mask_cover"]
+        # ratio = ee.Number(feat.get('mask_cover'))
+        # the last line should work, but it doesn't, I don't know why
+        assert isclose(ratio, 0)
 
     def test_deprecated_mask_cover(self):
         with pytest.deprecated_call():
             image = geetools.algorithms.maskCover(self.image)
-            assert isclose(image.get("mask_cover").getInfo(), 99.2)
+            assert isclose(image.get("mask_cover").getInfo(), 18.04, rel_tol=0.01)
 
     @property
     def image(self):
-        image_id = "COPERNICUS/S2_SR_HARMONIZED/20210105T100319_20210105T100317_T32TQM"
+        image_id = "COPERNICUS/S2_SR_HARMONIZED/20180401T100019_20180401T100022_T32TQM"
         image = ee.Image(image_id)
         qa = image.select("QA60")
         cloudBitMask, cirrusBitMask = 1 << 10, 1 << 11