Add Collection.distance.

PiperOrigin-RevId: 651917385

Author: schwehr

python/ee/collection.py

@@ -13,13 +13,18 @@
 
 from ee import _utils
 from ee import apifunction
+from ee import computedobject
 from ee import deprecation
 from ee import ee_date
 from ee import ee_exception
+from ee import ee_number
 from ee import element
 from ee import filter as ee_filter
 from ee import function
 from ee import geometry as ee_geometry
+from ee import image
+
+_NumberType = Union[float, ee_number.Number, computedobject.ComputedObject]
 
 
 class Collection(element.Element):
@@ -60,6 +65,35 @@ def reset(cls) -> None:
   def name() -> str:
     return 'Collection'
 
+  def distance(
+      self,
+      searchRadius: Optional[_NumberType] = None,
+      maxError: Optional[_NumberType] = None,
+  ) -> image.Image:
+    """Returns a distance image for the collection.
+
+    Produces a DOUBLE image where each pixel is the distance in meters from the
+    pixel center to the nearest Point, LineString, or polygonal boundary in the
+    collection. Note distance is also measured within interiors of polygons.
+    Pixels that are not within 'searchRadius' meters of a geometry will be
+    masked out.
+
+    Distances are computed on a sphere, so there is a small error proportional
+    to the latitude difference between each pixel and the nearest geometry.
+
+    Args:
+      searchRadius: Maximum distance in meters from each pixel to look for
+        edges. Pixels will be masked unless there are edges within this
+        distance.
+      maxError: Maximum reprojection error in meters, only used if the input
+        polylines require reprojection. If '0' is provided, then this operation
+        will fail if projection is required.
+    """
+
+    return apifunction.ApiFunction.call_(
+        'Collection.distance', self, searchRadius, maxError
+    )
+
   @staticmethod
   def elementType() -> Type[element.Element]:
     """Returns the type of the collection's elements."""
@@ -274,4 +308,3 @@ def sort(self, prop: str, ascending: Optional[bool] = None) -> Any:
       args['ascending'] = ascending
     return self._cast(
         apifunction.ApiFunction.apply_('Collection.limit', args))
-

python/ee/tests/featurecollection_test.py

@@ -53,7 +53,7 @@ def make_expression_graph(
     }
 }
 
-class FeatureCollectionTestCase(apitestcase.ApiTestCase):
+class FeatureCollectionTest(apitestcase.ApiTestCase):
 
   def test_constructors(self):
     """Verifies that constructors understand valid parameters."""
@@ -242,6 +242,24 @@ def test_copy_properties(self):
     result = json.loads(expression.serialize())
     self.assertEqual(expect, result)
 
+  def test_distance(self):
+    # Inherited from Collection.distance.
+    features = ee.FeatureCollection('a')
+    search_radius = 1.1
+    max_error = 2.2
+    expect = make_expression_graph({
+        'arguments': {
+            'features': FEATURES_A,
+            'searchRadius': {'constantValue': search_radius},
+            'maxError': {'constantValue': max_error},
+        },
+        # Not FeatureCollection.
+        'functionName': 'Collection.distance',
+    })
+    expression = features.distance(search_radius, max_error)
+    result = json.loads(expression.serialize())
+    self.assertEqual(expect, result)
+
   def test_inverse_distance(self):
     a_range = 2
     property_name = 'property name'

python/ee/tests/imagecollection_test.py

@@ -55,7 +55,7 @@ def make_expression_graph(
 }
 
 
-class ImageCollectionTestCase(apitestcase.ApiTestCase):
+class ImageCollectionTest(apitestcase.ApiTestCase):
 
   def test_image_collection_constructors(self):
     """Verifies that constructors understand valid parameters."""
@@ -211,6 +211,25 @@ def test_copy_properties(self):
     result = json.loads(expression.serialize())
     self.assertEqual(expect, result)
 
+  def test_distance(self):
+    # Inherited from Collection.distance.
+    features = ee.ImageCollection('a')
+    search_radius = 1.1
+    max_error = 2.2
+    expect = make_expression_graph({
+        'arguments': {
+            'features': IMAGES_A,
+            'searchRadius': {'constantValue': search_radius},
+            'maxError': {'constantValue': max_error},
+        },
+        # Not FeatureCollection.
+        'functionName': 'Collection.distance',
+    })
+    expression = features.distance(search_radius, max_error)
+    result = json.loads(expression.serialize())
+    self.assertEqual(expect, result)
+
+
   def test_forma_trend(self):
     covariates = ee.ImageCollection('b')
     window_size = 3