FarmVibes.AI 28.05

docs/requirements.txt

@@ -1,7 +1,7 @@
 docutils==0.18.1
-sphinx==6.1.3
-sphinx_rtd_theme==1.2.0
+sphinx==7.1.2
+sphinx_rtd_theme==2.0.0
 sphinxcontrib.mermaid==0.8.1
-myst_parser==1.0.0
-sphinx_autodoc_typehints==1.22
-sphinxcontrib-openapi==0.8.4
+myst_parser==2.0.0
+sphinx_autodoc_typehints==2.0.1
+sphinxcontrib-openapi==0.8.4

docs/source/conf.py

@@ -23,13 +23,24 @@
     "myst_parser",
     "sphinx_autodoc_typehints",
     "sphinxcontrib.openapi",
+    "sphinx.ext.napoleon",
 ]
 
 autosummary_generate = True
 autodoc_member_order = "groupwise"
+autodoc_typehints = "description"
+autodoc_typehints_description_target = "documented"
+autodoc_inherit_docstrings = False
+autoclass_content = "class"
 myst_heading_anchors = 3
+typehints_document_rtype = False
 typehints_use_rtype = False
 typehints_defaults = "comma"
+always_use_bars_union = True
+napoleon_use_rtype = False
+napoleon_google_docstring = True
+napoleon_numpy_docstring = False
+napoleon_include_init_with_doc = False
 
 sys.path.insert(0, os.path.abspath("../../src"))
 

docs/source/docfiles/markdown/NOTEBOOK_LIST.md

@@ -34,6 +34,8 @@ We organize available notebooks in the following topics:
 <details>
 <summary> BingMaps </summary>
 
+- [`Automatic Segmentation of BingMaps basemaps` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/segment_anything/basemap_automatic_segmentation.ipynb)
+
 - [`Segment Anything Model Workflow (BingMaps basemap)` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/segment_anything/basemap_segmentation.ipynb)
 
 
@@ -152,6 +154,10 @@ We organize available notebooks in the following topics:
 <details>
 <summary> Remote Sensing </summary>
 
+- [`Automatic Segmentation of BingMaps basemaps` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/segment_anything/basemap_automatic_segmentation.ipynb)
+
+- [`Automatic Segmentation of Sentinel-2` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/segment_anything/sentinel2_automatic_segmentation.ipynb)
+
 - [`Crop cycle detection` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/crop_cycles/crop_cycles.ipynb)
 
 - [`Crop land segmentation (1/4) - dataset generation` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/crop_segmentation/01_dataset_generation.ipynb)
@@ -192,6 +198,8 @@ We organize available notebooks in the following topics:
 
 - [`Segment Anything Model Workflow (Sentinel-2)` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/segment_anything/sentinel2_segmentation.ipynb)
 
+- [`Spectral Extension` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/spectral_extension/spectral_extension.ipynb)
+
 - [`Spectral indices` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sentinel/spectral_indices.ipynb)
 
 - [`Timelapse visualization` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sentinel/timelapse_visualization.ipynb)
@@ -203,6 +211,10 @@ We organize available notebooks in the following topics:
 <details>
 <summary> Segment Anything Model </summary>
 
+- [`Automatic Segmentation of BingMaps basemaps` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/segment_anything/basemap_automatic_segmentation.ipynb)
+
+- [`Automatic Segmentation of Sentinel-2` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/segment_anything/sentinel2_automatic_segmentation.ipynb)
+
 - [`Field boundary segmentation (SAM exploration)` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/segment_anything/sam_exploration.ipynb)
 
 - [`Field-level Irrigation Classification` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/irrigation/field_level_irrigation_classification.ipynb)
@@ -220,6 +232,8 @@ We organize available notebooks in the following topics:
 <details>
 <summary> Sentinel </summary>
 
+- [`Automatic Segmentation of Sentinel-2` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/segment_anything/sentinel2_automatic_segmentation.ipynb)
+
 - [`Field boundary segmentation (SAM exploration)` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/segment_anything/sam_exploration.ipynb)
 
 - [`Field-level spectral indices` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sentinel/field_level_spectral_indices.ipynb)
@@ -238,6 +252,8 @@ We organize available notebooks in the following topics:
 
 - [`Segment Anything Model Workflow (Sentinel-2)` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/segment_anything/sentinel2_segmentation.ipynb)
 
+- [`Spectral Extension` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/spectral_extension/spectral_extension.ipynb)
+
 - [`Spectral indices` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sentinel/spectral_indices.ipynb)
 
 
@@ -356,6 +372,10 @@ We organize available notebooks in the following topics:
 
 ## Notebooks description
 
+- [`Automatic Segmentation of BingMaps basemaps` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/segment_anything/basemap_automatic_segmentation.ipynb) : Automatically segment BingMaps basemaps with SAM workflow.
+
+- [`Automatic Segmentation of Sentinel-2` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/segment_anything/sentinel2_automatic_segmentation.ipynb) : Automatically segment Sentinel-2 imagery with SAM workflow.
+
 - [`Carbon sequestration evaluation with Microsoft Azure Data Manager for Agriculture (ADMAg) and COMET-Farm API` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/admag/azure_data_manager_for_agriculture_and_comet_farm_api_example.ipynb) : Derive carbon sequestration information with COMET-Farm API for agricultural fields, using Azure Data Manager for Agriculture to retrieve farming data.
 
 - [`Crop cycle detection` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/crop_cycles/crop_cycles.ipynb) : Run time-series analysis over NDVI data to detect the number of crop cycles in a year for a certain region.
@@ -414,6 +434,8 @@ We organize available notebooks in the following topics:
 
 - [`Segment Anything Model Workflow (Sentinel-2)` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/segment_anything/sentinel2_segmentation.ipynb) : Segment Sentinel-2 imagery with SAM workflow.
 
+- [`Spectral Extension` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/spectral_extension/spectral_extension.ipynb)  (~10 minutes) : Generate high-resolution multispectral data by combining high-resolution drone imagery and multispectral Sentinel-2 data.
+
 - [`Spectral indices` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sentinel/spectral_indices.ipynb) : Compute and visualize spectral indices from Sentinel-2 imagery.
 
 - [`Timelapse visualization` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sentinel/timelapse_visualization.ipynb) : Generate a timelapse of SpaceEye and NDVI rasters.

docs/source/docfiles/markdown/REST_API.md

@@ -112,108 +112,62 @@ Which would generate the following json:
 
 ```json
 {
-  "name": "SAM segmentation",
-  "workflow": "farm_ai/segmentation/segment_s2",
-  "parameters": null,
-  "user_input": {
-    "user_input": {
-      "type": "Feature",
-      "stac_version": "1.0.0",
-      "id": "f6465ad0-5e01-4792-ad99-a0bd240c1e7d",
-      "properties": {
-        "start_datetime": "2020-05-01T00:00:00+00:00",
-        "end_datetime": "2020-05-05T00:00:00+00:00",
-        "datetime": "2020-05-01T00:00:00Z"
-      },
-      "geometry": {
-        "type": "Polygon",
-        "coordinates": [
-          [
-            [
-              -119.14896203939314,
-              46.51578909859286
-            ],
-            [
-              -119.14896203939314,
-              46.37578909859286
-            ],
-            [
-              -119.28896203939313,
-              46.37578909859286
-            ],
-            [
-              -119.28896203939313,
-              46.51578909859286
-            ],
-            [
-              -119.14896203939314,
-              46.51578909859286
-            ]
-          ]
-        ]
-      },
-      "links": [],
-      "assets": {},
-      "bbox": [
-        -119.28896203939313,
-        46.37578909859286,
-        -119.14896203939314,
-        46.51578909859286
-      ],
-      "stac_extensions": [],
-      "terravibes_data_type": "DataVibe"
-    },
-    "prompts": {
-      "type": "Feature",
-      "stac_version": "1.0.0",
-      "id": "geo_734c6441-cb25-4c40-8204-6b7286f24bb9",
-      "properties": {
-        "urls": [
-          "/mnt/734c6441-cb25-4c40-8204-6b7286f24bb9_geometry_collection.geojson"
-        ],
-        "start_datetime": "2020-05-01T00:00:00+00:00",
-        "end_datetime": "2020-05-05T00:00:00+00:00",
-        "datetime": "2020-05-01T00:00:00Z"
-      },
-      "geometry": {
-        "type": "Polygon",
-        "coordinates": [
-          [
-            [
-              -119.14896203939314,
-              46.51578909859286
-            ],
-            [
-              -119.14896203939314,
-              46.37578909859286
-            ],
-            [
-              -119.28896203939313,
-              46.37578909859286
-            ],
-            [
-              -119.28896203939313,
-              46.51578909859286
-            ],
-            [
-              -119.14896203939314,
-              46.51578909859286
-            ]
-          ]
-        ]
-      },
-      "links": [],
-      "assets": {},
-      "bbox": [
-        -119.28896203939313,
-        46.37578909859286,
-        -119.14896203939314,
-        46.51578909859286
-      ],
-      "stac_extensions": [],
-      "terravibes_data_type": "ExternalReferenceList"
+    'name': 'SAM segmentation',
+    'workflow': 'farm_ai/segmentation/segment_s2',
+    'parameters': None,
+    'user_input': {
+        'user_input': {
+            'type': 'Feature',
+            'stac_version': '1.0.0',
+            'id': 'f6465ad0-5e01-4792-ad99-a0bd240c1e7d',
+            'properties': {
+                'start_datetime': '2020-05-01T00:00:00+00:00',
+                'end_datetime': '2020-05-05T00:00:00+00:00',
+                'datetime': '2020-05-01T00:00:00Z'
+            },
+            'geometry': {'type': 'Polygon',
+                'coordinates': (((-119.14896203939314, 46.51578909859286),
+                (-119.14896203939314, 46.37578909859286),
+                (-119.28896203939313, 46.37578909859286),
+                (-119.28896203939313, 46.51578909859286),
+                (-119.14896203939314, 46.51578909859286)),)
+                },
+            'links': [],
+            'assets': {},
+            'bbox': [-119.28896203939313,
+                46.37578909859286,
+                -119.14896203939314,
+                46.51578909859286],
+            'stac_extensions': [],
+            'terravibes_data_type': 'DataVibe'
+            },
+        'prompts': {
+            'type': 'Feature',
+            'stac_version': '1.0.0',
+            'id': 'geo_734c6441-cb25-4c40-8204-6b7286f24bb9',
+            'properties': {
+                'urls': ['/mnt/734c6441-cb25-4c40-8204-6b7286f24bb9_geometry_collection.geojson'],
+                'start_datetime': '2020-05-01T00:00:00+00:00',
+                'end_datetime': '2020-05-05T00:00:00+00:00',
+                'datetime': '2020-05-01T00:00:00Z'
+                },
+            'geometry': {'type': 'Polygon',
+                'coordinates': (((-119.14896203939314, 46.51578909859286),
+                (-119.14896203939314, 46.37578909859286),
+                (-119.28896203939313, 46.37578909859286),
+                (-119.28896203939313, 46.51578909859286),
+                (-119.14896203939314, 46.51578909859286)),)
+                },
+            'links': [],
+            'assets': {},
+            'bbox': [-119.28896203939313,
+                46.37578909859286,
+                -119.14896203939314,
+                46.51578909859286],
+            'stac_extensions': [],
+            'terravibes_data_type': 'ExternalReferenceList'
+        }
     }
-  }
 }
 ```
 

docs/source/docfiles/markdown/SECRETS.md

@@ -82,26 +82,23 @@ farmvibes-ai <local | remote> delete-secret <key>
 - **NOAA GFS SAS token** (parameter `noaa_gfs_token` with default secret key `noaa-gfs-sas`).
   - `data_ingestion/weather/get_forecast`
 
-- **SciHub username** and **password** (parameters `scihub_user` and `scihub_password`, and default secret keys `scihub-user` and `scihub-password`, respectively).
-  - `data_ingestion/sentinel1/preprocess_s1`
-
-- **Planetary computer API key**. By default, FarmVibes.AI workflows access the Planetary Computer catalog anonymously, when possible. However, we recommend registering for an API key [(see more information here)](https://planetarycomputer.microsoft.com/docs/overview/about/) to avoid being throttled.
+- **Planetary computer API key**. The API key is required for workflows that download Sentinel-1 data. For other workflows, the key is optional and avoids being throttled. If not provided, FarmVibes.AI access the Planetary Computer catalog anonymously. To register for an API key, [(see more information here)](https://planetarycomputer.microsoft.com/docs/overview/about/). 
   - `data_ingestion/dem/download_dem`
   - `data_ingestion/landsat/preprocess_landsat`
   - `data_ingestion/naip/download_naip`
-  - `data_ingestion/sentinel1/preprocess_s1`
+  - `data_ingestion/sentinel1/preprocess_s1` (Required)
   - `data_ingestion/sentinel2/preprocess_s2`
   - `data_ingestion/sentinel2/preprocess_s2_improved_mask`
-  - `data_ingestion/spaceeye/spaceeye`
+  - `data_ingestion/spaceeye/spaceeye` (Required)
   - `data_ingestion/spaceeye/spaceeye_interpolation`
-  - `data_ingestion/spaceeye/spaceeye_preprocess`
+  - `data_ingestion/spaceeye/spaceeye_preprocess` (Required)
   - `farm_ai/agriculture/canopy_cover`
-  - `farm_ai/agriculture/change_detection`
+  - `farm_ai/agriculture/change_detection` (Required)
   - `farm_ai/agriculture/emergence_summary`
   - `farm_ai/agriculture/methane_index`
   - `farm_ai/agriculture/ndvi_summary`
-  - `farm_ai/agriculture/conservation_practices`
   - `farm_ai/agriculture/landsat_ndvi_trend`
+  - `farm_ai/land_cover_mapping/conservation_practices`
   - `ml/dataset_generation/datagen_crop_segmentation`
 
 ```{eval-rst}

docs/source/docfiles/markdown/WORKFLOW_LIST.md

@@ -118,7 +118,7 @@ Below is a list of all available workflows within the FarmVibes.AI platform. For
 
 - [`chunk_onnx/chunk_onnx_sequence` 📄](workflow_yaml/data_processing/chunk_onnx/chunk_onnx_sequence.md): Runs an Onnx model over all rasters in the input to produce a single raster.
 
-- [`clip/clip` 📄](workflow_yaml/data_processing/clip/clip.md): Performs a soft clip on an input raster based on a provided reference geometry.
+- [`clip/clip` 📄](workflow_yaml/data_processing/clip/clip.md): Performs a clip on an input raster based on a provided reference geometry.
 
 - [`gradient/raster_gradient` 📄](workflow_yaml/data_processing/gradient/raster_gradient.md): Computes the gradient of each band of the input raster with a Sobel operator.
 
@@ -172,6 +172,10 @@ Below is a list of all available workflows within the FarmVibes.AI platform. For
 
 - [`land_degradation/ndvi_linear_trend` 📄](workflow_yaml/farm_ai/land_degradation/ndvi_linear_trend.md): Computes the pixel-wise NDVI linear trend over the input raster.
 
+- [`segmentation/auto_segment_basemap` 📄](workflow_yaml/farm_ai/segmentation/auto_segment_basemap.md): Downloads basemap with BingMaps API and runs Segment Anything Model (SAM) automatic segmentation over them.
+
+- [`segmentation/auto_segment_s2` 📄](workflow_yaml/farm_ai/segmentation/auto_segment_s2.md): Downloads Sentinel-2 imagery and runs Segment Anything Model (SAM) automatic segmentation over them.
+
 - [`segmentation/segment_basemap` 📄](workflow_yaml/farm_ai/segmentation/segment_basemap.md): Downloads basemap with BingMaps API and runs Segment Anything Model (SAM) over them with points and/or bounding boxes as prompts.
 
 - [`segmentation/segment_s2` 📄](workflow_yaml/farm_ai/segmentation/segment_s2.md): Downloads Sentinel-2 imagery and runs Segment Anything Model (SAM) over them with points and/or bounding boxes as prompts.
@@ -196,8 +200,10 @@ Below is a list of all available workflows within the FarmVibes.AI platform. For
 
 - [`driveway_detection` 📄](workflow_yaml/ml/driveway_detection.md): Detects driveways in front of houses.
 
-- [`segment_anything/basemap_prompt_segmentation` 📄](workflow_yaml/ml/segment_anything/basemap_prompt_segmentation.md): Runs Segment Anything Model (SAM) over BingMaps basemap rasters with points and/or bounding boxes as prompts.
+- [`segment_anything/automatic_segmentation` 📄](workflow_yaml/ml/segment_anything/automatic_segmentation.md): Runs a Segment Anything Model (SAM) automatic segmentation over input rasters.
+
+- [`segment_anything/prompt_segmentation` 📄](workflow_yaml/ml/segment_anything/prompt_segmentation.md): Runs Segment Anything Model (SAM) over input rasters with points and/or bounding boxes as prompts.
 
-- [`segment_anything/s2_prompt_segmentation` 📄](workflow_yaml/ml/segment_anything/s2_prompt_segmentation.md): Runs Segment Anything Model (SAM) over Sentinel-2 rasters with points and/or bounding boxes as prompts.
+- [`spectral_extension` 📄](workflow_yaml/ml/spectral_extension.md): Generates high-resolution Sentinel-2 bands by combining UAV and Sentinel-2 data.
 
 

docs/source/docfiles/markdown/data_types_diagram/core_types_hierarchy.md

@@ -8,6 +8,8 @@ classDiagram
   }
   class CarbonOffsetInfo {
   }
+  class ChipWindow {
+  }
   class DataSequence {
   }
   class DataSummaryStatistics {

docs/source/docfiles/markdown/data_types_diagram/rasters_hierarchy.md

@@ -38,6 +38,8 @@ classDiagram
   }
   class RasterSequence {
   }
+  class SamMaskRaster {
+  }
   DataSequence --|> DataVibe
   DataVibe --|> BaseVibe
   DemProduct --|> DataVibe
@@ -60,6 +62,7 @@ classDiagram
   RasterIlluminance --|> DataVibe
   RasterSequence --|> DataSequence
   RasterSequence --|> Raster
+  SamMaskRaster --|> CategoricalRaster
 
 
 </div>

docs/source/docfiles/markdown/workflow_yaml/data_ingestion/spaceeye/spaceeye_preprocess_ensemble.md

@@ -32,7 +32,7 @@ Runs the SpaceEye preprocessing pipeline with an ensemble of cloud segmentation
 
 ## Parameters
 
-- **pc_key**: Optional Planetary Computer API key.
+- **pc_key**: Planetary Computer API key.
 
 ## Tasks
 
@@ -82,7 +82,7 @@ description:
     s1_raster: Sentinel-1 rasters.
     cloud_mask: Cloud and cloud shadow mask.
   parameters:
-    pc_key: Optional Planetary Computer API key.
+    pc_key: Planetary Computer API key.
 
 
 ```