update branch

.github/workflows/unit.yaml

@@ -53,7 +53,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest]
-        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
         include:
           - os: macos-latest # macos test
             python-version: "3.12"

docs/conf.py

@@ -20,7 +20,7 @@
 project = "geetools"
 author = "Rodrigo E. Principe"
 copyright = f"2017-{datetime.now().year}, {author}"
-release = "1.17.2"
+release = "1.18.0"
 
 # -- General configuration -----------------------------------------------------
 extensions = [

geetools/__init__.py

@@ -37,7 +37,7 @@
 __title__ = "geetools"
 __summary__ = "A set of useful tools to use with Google Earth Engine Python" "API"
 __uri__ = "http://geetools.readthedocs.io"
-__version__ = "1.17.2"
+__version__ = "1.18.0"
 
 __author__ = "Rodrigo E. Principe"
 __email__ = "fitoprincipe82@gmail.com"

geetools/ee_asset.py

@@ -8,6 +8,7 @@
 
 import ee
 import ee.data
+from ee._state import get_state
 
 from .accessors import _register_extention
 from .utils import format_description
@@ -24,7 +25,7 @@ def __init__(self, *args):
             An asset cannot be an absolute path like in a normal filesystem and thus any trailing "/" will be removed.
         """
         if len(args) == 0:
-            self._path = f"projects/{ee.data._cloud_api_user_project}/assets/"
+            self._path = f"projects/{get_state().cloud_api_user_project}/assets/"
         else:
             self._path = args[0]._path if isinstance(args[0], Asset) else PurePosixPath(*args)
             project_assets = PurePosixPath(str(self._path)[1:])
@@ -90,7 +91,7 @@ def home(cls) -> Asset:
 
                 ee.Asset.home()
         """
-        return cls(f"projects/{ee.data._cloud_api_user_project}/assets/")
+        return cls(f"projects/{get_state().cloud_api_user_project}/assets/")
 
     def as_posix(self) -> str:
         """Return the asset id as a posix path.
@@ -162,7 +163,7 @@ def is_user_project(self, raised: bool = False) -> bool:
             return True
         else:
             if raised is True:
-                user_project = ee.data._cloud_api_user_project
+                user_project = get_state().cloud_api_user_project
                 msg = f"Asset {self.as_posix()} is not in the same project as the user ({user_project})"
                 raise ValueError(msg)
             else:
@@ -541,7 +542,7 @@ def owner(self):
         self.is_absolute(raised=True)
         return self.parts[1]
 
-    def move(self, new_asset: Asset, overwrite: bool = False) -> Asset:
+    def move(self, new_asset: os.PathLike, overwrite: bool = False) -> Asset:
         """Move the asset to a target destination.
 
         Move this asset (any type) to the given target, and return a new ``Asset`` instance
@@ -564,6 +565,7 @@ def move(self, new_asset: Asset, overwrite: bool = False) -> Asset:
                 asset.move(new_asset, overwrite=False)
         """
         # copy the assets
+        new_asset = new_asset if isinstance(new_asset, Asset) else ee.Asset(str(new_asset))
         self.copy(new_asset, overwrite=overwrite)
 
         # delete the original
@@ -648,7 +650,7 @@ def rmdir(self, recursive: bool = False, dry_run: bool | None = None) -> list:
         self.exists(raised=True)
         return self.delete(recursive, dry_run)
 
-    def copy(self, new_asset: Asset, overwrite: bool = False) -> Asset:
+    def copy(self, new_asset: os.PathLike, overwrite: bool = False) -> Asset:
         """Copy the asset to a target destination.
 
         Copy this asset (any type) to the given target, and return a new ``Asset`` instance
@@ -671,6 +673,7 @@ def copy(self, new_asset: Asset, overwrite: bool = False) -> Asset:
                 asset.copy(new_asset, overwrite=False)
         """
         # exit if the destination asset exist and overwrite is False
+        new_asset = new_asset if isinstance(new_asset, Asset) else ee.Asset(str(new_asset))
         if new_asset.exists() and overwrite is False:
             raise ValueError(f"Asset {new_asset.as_posix()} already exists.")
 
@@ -782,6 +785,11 @@ def date_in_str(d: str | int | float | datetime | date) -> str:
                 d = datetime.fromtimestamp(int(d) / 1000).isoformat() + "Z"
             return str(d)  # if any other format is used, we will simply return it as a string
 
+        # early exit if kwargs is empty
+        if len(kwargs) == 0:
+            return self
+
+        # Convert the system properties to the correct format
         if "system:time_start" in kwargs:
             kwargs["system:time_start"] = date_in_str(kwargs.pop("system:time_start"))
         if "system:time_end" in kwargs:

geetools/ee_authenticate.py

@@ -1,6 +1,7 @@
 """Toolbox for the :py:func:`ee.Authenticate` function."""
 from __future__ import annotations
 
+import json
 import os
 from contextlib import suppress
 from pathlib import Path
@@ -17,14 +18,15 @@ class AuthenticateAccessor:
     """Create an accessor for the :py:func:`ee.Authenticate` function."""
 
     @staticmethod
-    def new_user(name: str = "", credential_pathname: str | os.PathLike = ""):
+    def new_user(name: str = "", credential_pathname: str | os.PathLike = "", key_data: dict | None = None):
         """Authenticate the user and save the credentials in a specific folder.
 
         Equivalent to :py:func:`ee.Authenticate` but where the registered user will not be the default one (the one you get when running :py:func:`ee.Initialize`).
 
         Args:
             name: The name of the user. If not set, it will reauthenticate default.
             credential_pathname: The path to the folder where the credentials are stored. If not set, it uses the default path.
+            key_data: The json private key of the service account as a dict object. If not set, it will use the web-based authentication.
 
         Example:
             .. code-block:: python
@@ -48,10 +50,22 @@ def new_user(name: str = "", credential_pathname: str | os.PathLike = ""):
         default = Path(ee.oauth.get_credentials_path())
 
         with TemporaryDirectory() as dir:
+
+            # move the existing credentials to a safe place
             with suppress(FileNotFoundError):
                 move(default, Path(dir) / default.name)
-            ee.Authenticate()
+
+                # save the credentials passed to key_data or alternatively run the
+                # web-based authentication that will write the credentials to the same file
+                if key_data is not None:
+                    default.write_text(json.dumps(key_data))
+                else:
+                    ee.Authenticate()
+
+            # move the new credentials to the desired name
             move(default, credential_path / name)
+
+            # restore the previous default credentials
             with suppress(FileNotFoundError):
                 move(Path(dir) / default.name, default)
 

geetools/ee_export.py

@@ -72,12 +72,11 @@ def toAsset(
             ee.data.createAsset({"type": "IMAGE_COLLECTION"}, aid.as_posix())
 
             # loop over the collection and export each image
-            nb_images = imagecollection.size().getInfo()
-            imageList = imagecollection.toList(nb_images)
+            system_indices = imagecollection.aggregate_array("system:index").getInfo()
             task_list = []
-            for i in range(nb_images):
+            for sys_idx in system_indices:
                 # extract image information
-                locImage = ee.Image(imageList.get(i))
+                locImage = imagecollection.filter(ee.Filter.eq(index_property, sys_idx)).first()
                 loc_id = locImage.get(index_property).getInfo()
 
                 # override the parameters related to the image itself
@@ -135,12 +134,11 @@ def toDrive(
             fid = folder if folder else description
 
             # loop over the collection and export each image
-            nb_images = imagecollection.size().getInfo()
-            imageList = imagecollection.toList(nb_images)
+            system_indices = imagecollection.aggregate_array("system:index").getInfo()
             task_list = []
-            for i in range(nb_images):
+            for sys_idx in system_indices:
                 # extract image information
-                locImage = ee.Image(imageList.get(i))
+                locImage = imagecollection.filter(ee.Filter.eq(index_property, sys_idx)).first()
                 loc_id = locImage.get(index_property).getInfo()
 
                 # override the parameters related to the image itself
@@ -199,12 +197,11 @@ def toCloudStorage(
             fid = folder if folder else description
 
             # loop over the collection and export each image
-            nb_images = imagecollection.size().getInfo()
-            imageList = imagecollection.toList(nb_images)
+            system_indices = imagecollection.aggregate_array("system:index").getInfo()
             task_list = []
-            for i in range(nb_images):
+            for sys_idx in system_indices:
                 # extract image information
-                locImage = ee.Image(imageList.get(i))
+                locImage = imagecollection.filter(ee.Filter.eq(index_property, sys_idx)).first()
                 loc_id = locImage.get(index_property).getInfo()
 
                 # override the parameters related to the image itself

geetools/ee_feature_collection.py

@@ -5,6 +5,7 @@
 
 import ee
 import geopandas as gpd
+import shapely
 from matplotlib import pyplot as plt
 from matplotlib.axes import Axes
 
@@ -711,7 +712,11 @@ def plot(
             gdf.plot(column=property, ax=ax, cmap=cmap)
 
     @classmethod
-    def fromGeoInterface(cls, data: dict | GeoInterface) -> ee.FeatureCollection:
+    def fromGeoInterface(
+        cls,
+        data: dict | GeoInterface,
+        crs: str = "EPSG:4326",
+    ) -> ee.FeatureCollection:
         """Create a :py:class:`ee.FeatureCollection` from a geo interface.
 
         The ``geo_interface`` is a protocol representing a vector collection as a python GeoJSON-like dictionary structure.
@@ -723,7 +728,7 @@ def fromGeoInterface(cls, data: dict | GeoInterface) -> ee.FeatureCollection:
 
         Parameters:
             data: The geo_interface to create the :py:class:`ee.FeatureCollection` from.
-            crs: The CRS to use for the FeatureCollection. Default to ``EPSG:4326``.
+            crs: The CRS of the input data. Defaults to "EPSG:4326".
 
         Returns:
             The created :py:class:`ee.FeatureCollection` from the geo_interface.
@@ -755,5 +760,109 @@ def fromGeoInterface(cls, data: dict | GeoInterface) -> ee.FeatureCollection:
         elif not isinstance(data, dict):
             raise ValueError("The data must be a geo_interface or a dictionary")
 
+        # ensure the geometries are 2D
+        gdf = gpd.GeoDataFrame.from_features(data["features"], crs=crs)
+        gdf.geometry = shapely.force_2d(gdf.geometry.values)
+        data = gdf.__geo_interface__
+
         # create the feature collection
         return ee.FeatureCollection(data)
+
+    def areaSort(self, ascending: bool = True) -> ee.FeatureCollection:
+        """Sort the features in the collection by area.
+
+        Args:
+            ascending: Whether to sort in ascending order.
+
+        Returns:
+            The sorted collection.
+
+        Examples:
+            .. jupyter-execute::
+
+                import ee, geetools
+                from geetools.utils import initialize_documentation
+
+                initialize_documentation()
+
+                fc = ee.FeatureCollection("FAO/GAUL/2015/level0").limit(5)
+                fc = fc.geetools.areaSort()
+                fc.aggregate_array("ADM0_NAME").getInfo()
+        """
+        # generate an area property
+        name = "__geetools_area__"
+        fc = self._obj.map(lambda feat: feat.set(name, feat.geometry().area(1)))
+
+        # sort by area and remove the property from the output
+        properties = fc.first().propertyNames().remove(name)
+        return fc.sort(name, ascending).map(lambda feat: feat.select(properties))
+
+    def filterGeometryType(self, type_: str | ee.String) -> ee.FeatureCollection:
+        """Filter the collection by geometry type.
+
+        Only keep in the Final featureCollection the Feature with the specified geometry type.
+        Can be combined with ``breakGeometries`` to filter out multi geometries.
+
+        Args:
+            type_: The geometry type to filter on. Must be one of the `GEE compatible types <https://developers.google.com/earth-engine/guides/geometries>`__
+
+        Returns:
+            The filtered collection
+
+        Examples:
+            .. jupyter-execute::
+
+                import ee, geetools
+                from geetools.utils import initialize_documentation
+
+                initialize_documentation()
+
+                geoms = [ee.Geometry.Point([0, 0]), ee.Geometry.Point([0, 0]).buffer(1)]
+                fc = ee.FeatureCollection([ee.Feature(g, {"test": "test"}) for g in geoms])
+                fc = fc.geetools.breakGeometries().geetools.filterGeometryType("Point")
+                fc.aggregate_array("test").getInfo()
+        """
+        # extract the properties of the features before filtering
+        # and create an extra column with the geometry type
+        type_, name = ee.String(type_), "__geetools_type__"
+        properties = self._obj.first().propertyNames()
+        fc = self._obj.map(lambda feat: feat.set(name, feat.geometry().type()))
+
+        # filter the collection and remove the extra column
+        fc = fc.filter(ee.Filter.eq(name, type_)).select(properties)
+
+        return ee.FeatureCollection(fc)
+
+    def breakGeometries(self) -> ee.FeatureCollection:
+        """Break every feature using geometries into it's constituents.
+
+        Each Geometry that is using a multi parts geometry type will be duplicated
+        into multiple features with each one carrying one of the constituent of the multiPolygon.
+
+        Returns:
+            ee.FeatureCollection: The collection with the broken down geometries
+
+        Examples:
+            .. code-block:: python
+
+                import ee, geetools
+                from geetools.utils import initialize_documentation
+
+                initialize_documentation()
+
+                multipoint = ee.Geometry.MultiPoint([ee.Geometry.Point([0, 0]), ee.Geometry.Point([1, 0])])
+                fc = ee.FeatureCollection([ee.Feature(multipoint, {"test": "test"})])
+                fc = fc.geetools.breakGeometries()
+                fc.aggregate_array("test").getInfo()
+        """
+        # helper function to break the geometry of a feature
+        def split(feat):
+            feat = ee.Feature(feat)
+            geometries = feat.geometry().geometries()
+            return geometries.map(lambda g: ee.Feature(ee.Geometry(g), feat.toDictionary()))
+
+        # apply the function to the collection and flatten the list as each feature
+        # can have multiple geometries (thus list of list) and we want a single list
+        list = self._obj.toList(self._obj.size()).map(split).flatten()
+
+        return ee.FeatureCollection(list)

geetools/ee_image.py

@@ -21,7 +21,7 @@
 from xee.ext import REQUEST_BYTE_LIMIT
 
 from .accessors import register_class_accessor
-from .utils import format_class_info, plot_data
+from .utils import area_units_to_m2, format_class_info, plot_data
 
 
 @register_class_accessor(ee.Image, "geetools")
@@ -2287,3 +2287,34 @@ def plot_hist(
         ax.legend(bbox_to_anchor=(1.02, 1), loc="upper left")
 
         return ax
+
+    @classmethod
+    def pixelArea(cls, area_unit: str = "m2", rename_to_units: bool = False) -> ee.Image:
+        """Extend the :py:method:`ee.Image.pixelArea` method by setting the unit of the output.
+
+        Args:
+            area_unit: the unit of the output area. can be one of "m2", "ha", "kha", "km2" or "acres".
+            rename_to_units: if ``True``, the output image will be renamed to the given unit.
+
+        Returns:
+            the area ``ee.Image`` using the given unit.
+
+        Examples:
+            .. jupyter-execute::
+
+                import ee, geetools
+                from geetools.utils import initialize_documentation
+
+                initialize_documentation()
+
+                hectares = ee.Image.geetools.pixelArea("ha").rename("ha")
+                acres = ee.Image.geetools.pixelArea("acres").rename("acres")
+                total = hectares.addBands(acres)
+
+                buffer = ee.Geometry.Point(0,0).buffer(100)
+                values = total.reduceRegion(ee.Reducer.mean(), buffer, 1)
+                values.getInfo()
+        """
+        name = area_unit if rename_to_units is True else "area"
+        divisor = area_units_to_m2(area_unit)
+        return ee.Image.pixelArea().divide(divisor).rename(name)