Merge pull request #28 from leftfield-geospatial/feature_s2_cloud_score

Feature s2 cloud score

README.rst

@@ -195,12 +195,11 @@ Composite the results of a Landsat-8 search, export to Earth Engine asset, and d
 
     geedim search -c l8-c2-l2 -s 2019-02-01 -e 2019-03-01 --bbox 23 -33 23.2 -33.2 composite -cm q-mosaic export --type asset --folder <your cloud project> --scale 30 --crs EPSG:3857 download
 
-Search for Sentinel-2 SR images with a cloudless portion of at least 60%, using the ``qa`` mask-method to identify
-clouds:
+Search for Sentinel-2 SR images with a cloudless portion of at least 60%, using the ``cloud-score`` mask-method to identify clouds:
 
 .. code:: shell
 
-   geedim config --mask-method qa search -c s2-sr --cloudless-portion 60 -s 2022-01-01 -e 2022-01-14 --bbox 24 -34 24.5 -33.5
+   geedim config --mask-method cloud-score search -c s2-sr-hm --cloudless-portion 60 -s 2022-01-01 -e 2022-01-14 --bbox 24 -34 24.5 -33.5
 
 .. cli_end
 
@@ -223,18 +222,18 @@ Example
    }
 
    # make collection and search, reporting cloudless portions
-   coll = gd.MaskedCollection.from_name('COPERNICUS/S2_SR')
+   coll = gd.MaskedCollection.from_name('COPERNICUS/S2_SR_HARMONIZED')
    coll = coll.search('2019-01-10', '2019-01-21', region, cloudless_portion=0)
    print(coll.schema_table)
    print(coll.properties_table)
 
    # create and download an image
-   im = gd.MaskedImage.from_id('COPERNICUS/S2_SR/20190115T080251_20190115T082230_T35HKC')
+   im = gd.MaskedImage.from_id('COPERNICUS/S2_SR_HARMONIZED/20190115T080251_20190115T082230_T35HKC')
    im.download('s2_image.tif', region=region)
 
    # composite search results and download
    comp_im = coll.composite()
-   comp_im.download('s2_comp_image.tif', region=region, crs='EPSG:32735', scale=30)
+   comp_im.download('s2_comp_image.tif', region=region, crs='EPSG:32735', scale=10)
 
 License
 -------

docs/api.rst

@@ -20,10 +20,7 @@ Initialisation
 Searching image collections
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-`Any Earth Engine image collection <https://developers.google.com/earth-engine/datasets/catalog>`_ can be searched with
-:class:`~geedim.collection.MaskedCollection`.  Here, we search for
-`Landsat-8 surface reflectance <https://developers.google.com/earth-engine/datasets/catalog/LANDSAT_LC08_C02_T1_L2>`_
-images over Stellenbosch, South Africa.
+`Any Earth Engine image collection <https://developers.google.com/earth-engine/datasets/catalog>`_ can be searched with :class:`~geedim.collection.MaskedCollection`.  Here, we search for `Landsat-8 surface reflectance <https://developers.google.com/earth-engine/datasets/catalog/LANDSAT_LC08_C02_T1_L2>`_ images over Stellenbosch, South Africa.
 
 .. literalinclude:: examples/api_getting_started.py
     :language: python
@@ -58,8 +55,7 @@ The output:
 Image creation and download
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Images can be created, masked and downloaded with the :class:`~geedim.mask.MaskedImage` class.  Typically, one would
-pass the Earth Engine image ID to :meth:`.MaskedImage.from_id` to create the image.
+Images can be created, masked and downloaded with the :class:`~geedim.mask.MaskedImage` class.  Typically, one would pass the Earth Engine image ID to :meth:`.MaskedImage.from_id` to create the image.
 
 .. literalinclude:: examples/api_getting_started.py
     :language: python
@@ -69,13 +65,10 @@ pass the Earth Engine image ID to :meth:`.MaskedImage.from_id` to create the ima
 Compositing
 ^^^^^^^^^^^
 
-Let's form a cloud/shadow-free composite of the search result images, using the *q-mosaic* method, then download
-the result.  By specifying the ``region`` parameter to :meth:`.MaskedCollection.composite`, we prioritise selection
-of pixels from the least cloudy images when forming the composite.
+Let's form a cloud/shadow-free composite of the search result images, using the *q-mosaic* method, then download the result.  By specifying the ``region`` parameter to :meth:`.MaskedCollection.composite`, we prioritise selection of pixels from the least cloudy images when forming the composite.
 
 .. note::
-    When downloading composite images, the ``region``, ``crs`` and ``scale`` parameters must be specified, as the image
-    has no fixed (known) projection.
+    When downloading composite images, the ``region``, ``crs`` and ``scale`` parameters must be specified, as the image has no fixed (known) projection.
 
 .. literalinclude:: examples/api_getting_started.py
     :language: python
@@ -92,7 +85,7 @@ take optional cloud/shadow masking ``**kwargs``.  See :meth:`.MaskedImage.__init
 parameters.
 
 Here, we create and download a cloud/shadow masked
-`Sentinel-2 image <https://developers.google.com/earth-engine/datasets/catalog/COPERNICUS_S2_SR>`_, specifying a cloud probability threshold of 30%.
+`Sentinel-2 image <https://developers.google.com/earth-engine/datasets/catalog/COPERNICUS_S2_SR>`_, specifying a cloud score threshold of 0.7.
 
 .. literalinclude:: examples/api_getting_started.py
     :language: python

docs/examples/api_getting_started.py

@@ -1,14 +1,14 @@
 # [initialise-start]
 import geedim as gd
+
 gd.Initialize()
 # [initialise-end]
 
 # [search-start]
 # geojson search polygon
 region = {
-    'type': 'Polygon', 'coordinates': [[
-        (19, -34), (19, -33.8), (18.8, -33.8), (18.8, -34), (19., -34)
-    ]]
+    'type': 'Polygon',
+    'coordinates': [[(19, -34), (19, -33.8), (18.8, -33.8), (18.8, -34), (19.0, -34)]],
 }
 
 # create & search a landsat-8 collection, reporting cloudless portions
@@ -22,35 +22,34 @@
 
 # [image-download-start]
 # create a landsat-8 image from its ID
-im = gd.MaskedImage.from_id(
-    'LANDSAT/LC08/C02/T1_L2/LC08_175083_20190117', mask=False)
+im = gd.MaskedImage.from_id('LANDSAT/LC08/C02/T1_L2/LC08_175083_20190117', mask=False)
 
 # download a region of the image with 'average' resampling to 60m pixels, and
 # data type conversion to 16 bit unsigned int
-im.download('landsat_8_image.tif', region=region, resampling='average',
-            scale=60, dtype='uint16')
+im.download('landsat_8_image.tif', region=region, resampling='average', scale=60, dtype='uint16')
 # [image-download-end]
 
 # [composite-start]
 # find a 'q-mosaic' composite image of the search result images, prioritising
 # the least cloudy image by specifying `region`
 comp_im = filt_coll.composite(method='q-mosaic', region=region)
 # download the composite, specifying crs, region, and scale
-comp_im.download('landsat_8_comp_image.tif', region=region, crs='EPSG:32634',
-                 scale=30)
+comp_im.download('landsat_8_comp_image.tif', region=region, crs='EPSG:32634', scale=30)
 # [composite-end]
 
 # [mask-start]
 # create a cloud/shadow masked Sentinel-2 image, specifying a cloud
-# probability threshold of 30%
+# score threshold of 0.7
 im = gd.MaskedImage.from_id(
-    'COPERNICUS/S2_SR/20190101T082331_20190101T084846_T34HCH', mask=True, prob=30)
+    'COPERNICUS/S2_SR_HARMONIZED/20190101T082331_20190101T084846_T34HCH', mask=True, score=0.7
+)
 # download a region of the masked image, downsampling to 20m pixels
-im.download('s2_sr_image.tif', region=region, scale=20, resampling='average')
+im.download('s2_sr_hm_image.tif', region=region, scale=20, resampling='average')
 # [mask-end]
 
 # [metadata-start]
 import rasterio as rio
+
 with rio.open('s2_sr_image.tif', 'r') as ds:
     print('Image properties:\n', ds.tags())
     print('Band names:\n', ds.descriptions)
@@ -59,8 +58,9 @@
 
 # [max_tile_size-start]
 import ee
+
 # create a computed ee.Image
-ee_im = ee.Image('COPERNICUS/S2_SR/20190101T082331_20190101T084846_T34HCH')
+ee_im = ee.Image('COPERNICUS/S2_SR_HARMONIZED/20190101T082331_20190101T084846_T34HCH')
 comp_im = ee_im.select('B3').entropy(ee.Kernel.square(5))
 
 # encapsulate in MaskedImage, and download with max_tile_size=8