Sync with prod branch

Co-authored-by: Alex Crown <[email protected]> Co-authored-by: Eduardo Rodrigues <[email protected]> Co-authored-by: Rafael Padilha <[email protected]> Co-authored-by: Renato Luiz de Freitas Cunha <[email protected]>
microsoft · Oct 26, 2023 · c3e0463 · c3e0463
1 parent 36b488c
commit c3e0463
Show file tree

Hide file tree

Showing 38 changed files with 916 additions and 442 deletions.
diff --git a/docs/source/docfiles/markdown/CACHE.md b/docs/source/docfiles/markdown/CACHE.md
@@ -1,4 +1,4 @@
-# FarmVibes.AI Data Management
+# Data Management
 
 FarmVibes.AI offers a scalable platform for processing large-scale geospatial data using reusable
 components. Besides breaking down computations spatially and temporally into parallel chunks,

diff --git a/docs/source/docfiles/markdown/NOTEBOOK_LIST.md b/docs/source/docfiles/markdown/NOTEBOOK_LIST.md
@@ -62,11 +62,13 @@ We organize available notebooks in the following topics:
 
 - [`Harvest and germination periods` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/harvest_period/ndvi_summary.ipynb)
 
+- [`Irrigation classification` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/irrigation/irrigation_classification.ipynb)
+
 - [`Land degradation` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/land_degradation/land_degradation.ipynb)
 
-- [`Nutrient Heatmap Estimation` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/heatmaps/nutrients_using_classification.ipynb)
+- [`Nutrient Heatmap Estimation - Classification` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/heatmaps/nutrients_using_classification.ipynb)
 
-- [`Nutrient Heatmap Estimation` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/heatmaps/nutrients_using_neighbors.ipynb)
+- [`Nutrient Heatmap Estimation - Neighbors` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/heatmaps/nutrients_using_neighbors.ipynb)
 
 - [`Nutrient Heatmap Estimation with ADMAg integration` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/heatmaps/nutrients_using_classification_admag.ipynb)
 
@@ -81,6 +83,8 @@ We organize available notebooks in the following topics:
 <details>
 <summary> Landsat </summary>
 
+- [`Irrigation classification` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/irrigation/irrigation_classification.ipynb)
+
 - [`Land degradation` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/land_degradation/land_degradation.ipynb)
 
 
@@ -96,9 +100,9 @@ We organize available notebooks in the following topics:
 
 - [`Micro climate prediction` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/deepmc/mc_forecast.ipynb)
 
-- [`Nutrient Heatmap Estimation` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/heatmaps/nutrients_using_classification.ipynb)
+- [`Nutrient Heatmap Estimation - Classification` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/heatmaps/nutrients_using_classification.ipynb)
 
-- [`Nutrient Heatmap Estimation` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/heatmaps/nutrients_using_neighbors.ipynb)
+- [`Nutrient Heatmap Estimation - Neighbors` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/heatmaps/nutrients_using_neighbors.ipynb)
 
 - [`Nutrient Heatmap Estimation with ADMAg integration` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/heatmaps/nutrients_using_classification_admag.ipynb)
 
@@ -142,6 +146,8 @@ We organize available notebooks in the following topics:
 
 - [`Investigating Amazon Rainforest deforestation with SpaceEye` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sentinel/sentinel_spaceeye.ipynb)
 
+- [`Irrigation classification` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/irrigation/irrigation_classification.ipynb)
+
 - [`Land degradation` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/land_degradation/land_degradation.ipynb)
 
 - [`Segment Anything Model Workflow` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/segment_anything/sam_workflow.ipynb)
@@ -170,9 +176,9 @@ We organize available notebooks in the following topics:
 
 - [`Investigating Amazon Rainforest deforestation with SpaceEye` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sentinel/sentinel_spaceeye.ipynb)
 
-- [`Nutrient Heatmap Estimation` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/heatmaps/nutrients_using_classification.ipynb)
+- [`Nutrient Heatmap Estimation - Classification` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/heatmaps/nutrients_using_classification.ipynb)
 
-- [`Nutrient Heatmap Estimation` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/heatmaps/nutrients_using_neighbors.ipynb)
+- [`Nutrient Heatmap Estimation - Neighbors` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/heatmaps/nutrients_using_neighbors.ipynb)
 
 - [`Nutrient Heatmap Estimation with ADMAg integration` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/heatmaps/nutrients_using_classification_admag.ipynb)
 
@@ -202,9 +208,9 @@ We organize available notebooks in the following topics:
 
 - [`Green House Gas fluxes` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/ghg_fluxes/ghg_fluxes.ipynb)
 
-- [`Nutrient Heatmap Estimation` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/heatmaps/nutrients_using_classification.ipynb)
+- [`Nutrient Heatmap Estimation - Classification` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/heatmaps/nutrients_using_classification.ipynb)
 
-- [`Nutrient Heatmap Estimation` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/heatmaps/nutrients_using_neighbors.ipynb)
+- [`Nutrient Heatmap Estimation - Neighbors` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/heatmaps/nutrients_using_neighbors.ipynb)
 
 - [`Nutrient Heatmap Estimation with ADMAg integration` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/heatmaps/nutrients_using_classification_admag.ipynb)
 
@@ -259,9 +265,9 @@ We organize available notebooks in the following topics:
 
 - [`Integration with ADMAg to compute NDVI summary` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/admag/azure_data_manager_for_agriculture_example.ipynb)
 
-- [`Nutrient Heatmap Estimation` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/heatmaps/nutrients_using_classification.ipynb)
+- [`Nutrient Heatmap Estimation - Classification` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/heatmaps/nutrients_using_classification.ipynb)
 
-- [`Nutrient Heatmap Estimation` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/heatmaps/nutrients_using_neighbors.ipynb)
+- [`Nutrient Heatmap Estimation - Neighbors` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/heatmaps/nutrients_using_neighbors.ipynb)
 
 - [`Nutrient Heatmap Estimation with ADMAg integration` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/heatmaps/nutrients_using_classification_admag.ipynb)
 
@@ -318,9 +324,9 @@ We organize available notebooks in the following topics:
 
 - [`Micro climate prediction` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/deepmc/mc_forecast.ipynb) : Train a model to predict micro climate parameters given global weather information and local weather station data.
 
-- [`Nutrient Heatmap Estimation` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/heatmaps/nutrients_using_classification.ipynb) : Using soil samples from a farm, train a Random Forest model to estimate a heatmap of soil nutrients.
+- [`Nutrient Heatmap Estimation - Classification` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/heatmaps/nutrients_using_classification.ipynb) : Using soil samples from a farm, train a Random Forest model to estimate a heatmap of soil nutrients.
 
-- [`Nutrient Heatmap Estimation` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/heatmaps/nutrients_using_neighbors.ipynb) : Using soil samples from a farm, train a Random Forest model to estimate a heatmap of soil nutrients.
+- [`Nutrient Heatmap Estimation - Neighbors` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/heatmaps/nutrients_using_neighbors.ipynb) : Estimate a heatmap of soil nutrients based on neighboring soil samples with location suggested by an optimal sensor placement workflow.
 
 - [`Nutrient Heatmap Estimation with ADMAg integration` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/heatmaps/nutrients_using_classification_admag.ipynb)  (~1GB, <1 minute) : Using soil samples from a farm retrieved with ADMAg, train a Random Forest model to estimate a heatmap of soil nutrients.
 

diff --git a/docs/source/docfiles/markdown/TROUBLESHOOTING.md b/docs/source/docfiles/markdown/TROUBLESHOOTING.md
@@ -41,6 +41,17 @@ This document compiles the most common issues encountered when installing and ru
 
 - **Cluster setup:**
 
+    <details>
+    <summary> How to change the storage location during cluster creation</summary>
+
+    You may change the storage location by defining the environment variable
+    `FARMVIBES_AI_STORAGE_PATH` prior to installation with the *farmvibes-ai*
+    command. Additionally, you may use the flag `--storage-path` when running
+    the `farmvibes-ai local setup` command. For more information, please refer
+    to the help message of the *farmvibes-ai* command.
+
+    </details>
+
     <details>
     <summary> Missing secrets</summary>
 
@@ -55,13 +66,15 @@ This document compiles the most common issues encountered when installing and ru
     </details>
 
     <details>
-    <summary> How to change the storage location during cluster creation</summary>
+    <summary> No route to the Rest-API </summary>
 
-    You may change the storage location by defining the environment variable
-    `FARMVIBES_AI_STORAGE_PATH` prior to installation with the *farmvibes-ai*
-    command. Additionally, you may use the flag `--storage-path` when running
-    the `farmvibes-ai local setup` command. For more information, please refer
-    to the help message of the *farmvibes-ai* command.
+    Building a cluster with the *farmvibes-ai* command will set up a Rest-API
+    service with an address visible only within the cluster. In case the client
+    cannot reach the Rest-API, make sure to restart the cluster with:
+
+    ```bash
+    farmvibes-ai local restart
+    ```
 
     </details>
 
@@ -90,18 +103,9 @@ This document compiles the most common issues encountered when installing and ru
     }
     ```
 
-    </details>
-
-    <details>
-    <summary> No route to the Rest-API </summary>
-
-    Building a cluster with the *farmvibes-ai* command will set up a Rest-API
-    service with an address visible only within the cluster. In case the client
-    cannot reach the Rest-API, make sure to restart the cluster with:
-
-    ```bash
-    farmvibes-ai local restart
-    ```
+    As an alternative you might also want to delete data from previous workflow runs
+    to free some space. For more information on how to do that and other data
+    management operations, please refer to the [Data Management user guide](CACHE.md).
 
     </details>
 
@@ -134,6 +138,42 @@ This document compiles the most common issues encountered when installing and ru
 
     </details>
 
+    <details>
+    <summary> Tasks fail with "Abnormal Termination"</summary>
+
+    Some workflows, such as the SpaceEye workflow (in the
+    `preprocess.s1.preprocess`) or the Segment Anything Model (SAM) workflow
+    might use a large amount of memory depending on the input area and/or time
+    range used for processing. When that's the case, the Operating System might
+    terminate the offending task, failing it and the workflow.
+
+    When inspecting the error reason, users might find a text that says `...
+    ProcessExpired: Abnormal termination`.
+
+    One solution is to request processing of a smaller region.
+
+    Another solution is to scale down the number of workers with the command
+    `~/.config/farmvibes-ai/kubectl scale deployment terravibes-worker
+    --replicas=1`.
+
+    If, even when doing the above, the task still fails, the Kubernetes cluster
+    might need to be migrated to a machine with more RAM.
+
+    </details>
+
+    <details>
+    <summary> Unable to find ONNX model when running workflows </summary>
+
+    Make sure the ONNX model was added to the FarmVibes.AI cluster:
+
+    ```bash
+    farmvibes-ai local add-onnx <onnx-model>
+    ```
+
+    If no output is generated, then your model was successfully added.
+
+    </details>
+
     <details>
     <summary> Verifying why a workflow run failed </summary>
 
@@ -162,19 +202,6 @@ This document compiles the most common issues encountered when installing and ru
 
     </details>
 
-    <details>
-    <summary> Unable to find ONNX model when running workflows </summary>
-
-    Make sure the ONNX model was added to the FarmVibes.AI cluster:
-
-    ```bash
-    farmvibes-ai local add-onnx <onnx-model>
-    ```
-
-    If no output is generated, then your model was successfully added.
-
-    </details>
-
     <details>
     <summary> Workflow run with 'pending' status indefinitally</summary>
 
@@ -186,26 +213,14 @@ This document compiles the most common issues encountered when installing and ru
 
     </details>
 
-  <details>
-  <summary> Tasks fail with "Abnormal Termination"</summary>
-
-  Some workflows, such as the SpaceEye workflow (in the
-  `preprocess.s1.preprocess`) or the Segment Anything Model (SAM) workflow
-  might use a large amount of memory depending on the input area and/or time
-  range used for processing. When that's the case, the Operating System might
-  terminate the offending task, failing it and the workflow.
-
-  When inspecting the error reason, users might find a text that says `...
-  ProcessExpired: Abnormal termination`.
+<br>
 
-  One solution is to request processing of a smaller region.
+- **Example notebooks:**
 
-  Another solution is to scale down the number of workers with the command
-  `~/.config/farmvibes-ai/kubectl scale deployment terravibes-worker
-  --replicas=1`.
+  <details>
+  <summary> Unable to import modules when running a notebook</summary>
 
-  If, even when doing the above, the task still fails, the Kubernetes cluster
-  might need to be migrated to a machine with more RAM.
+  Make sure you have installed and activated the conda environment provided with the notebook.
 
   </details>
 
@@ -241,17 +256,21 @@ This document compiles the most common issues encountered when installing and ru
 
   </details>
 
-<br>
-
-- **Example notebooks:**
-
   <details>
-  <summary> Unable to import modules when running a notebook</summary>
+  <summary> Unreliable segmentation mask when using bounding box as prompt</summary>
 
-  Make sure you have installed and activated the conda environment provided with the notebook.
+  As the input Sentinel-2 rasters may be considerably larger than the images expected by SAM, we split the rasters
+  into 1024 x 1024 chips (with an overlap defined by the `spatial_overlap` parameter of the workflow). This may lead to
+  corner cases that yield unreliable segmentation masks, especially when using a bounding box as prompt. To avoid
+  such cases, consider the following:
 
-  </details>
+  - Only a single bounding box is supported per prompt group (i.e., all points with the same `prompt_id`).
+  - We recommend providing at least one foreground point within the bounding box. Even though the model supports segmentating rasters solely with a bounding box, the results may be unreliable.
+  - If the prompt contains a foreground point outside the provided bounding box, the workflow will adjust the bounding box to include all foreground points in that prompt group.
+  - Background points outside the bounding box are ignored.
+  - Regions outside the bounding box will be masked out in the final segmentation mask.
 
+  </details>
 
 ```{eval-rst}
 .. autosummary::

diff --git a/docs/source/docfiles/markdown/WORKFLOW_LIST.md b/docs/source/docfiles/markdown/WORKFLOW_LIST.md
@@ -101,6 +101,8 @@ Below is a list of all available workflows within the FarmVibes.AI platform. For
 
 - [`chunk_onnx/chunk_onnx` 📄](workflow_yaml/data_processing/chunk_onnx/chunk_onnx.md): Run an Onnx model over all rasters in the input to produce a single raster.
 
+- [`chunk_onnx/chunk_onnx_sequence` 📄](workflow_yaml/data_processing/chunk_onnx/chunk_onnx_sequence.md): Run 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.
 
 - [`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.
@@ -109,6 +111,24 @@ Below is a list of all available workflows within the FarmVibes.AI platform. For
 nutrient information (Nitrogen, Carbon, pH, Phosphorus) to train a model using Random Forest classifier.
 The inference operation predicts nutrients in soil for the chosen farm boundary.
 
+The workflow generates a heatmap for selected nutrient. It relies on sample soil data that contain information of nutrients.
+The quantity of samples define the accuracy of the heat map generation. During the research performed testing with
+samples spaced at 200 feet, 100 feet and 50 feet. The 50 feet sample spaced distance provided results matching to the
+ground truth. Generating heatmap with this approach reduce the number of samples.
+It utilizes the logic below behind the scenes to generate heatmap.
+  - Read the sentinel raster provided.
+  - Sensor samples needs to be uploaded into prescriptions entity in Azure data manager for Agriculture (ADMAg). ADMAg is having hierarchy
+  to hold information of Farmer, Field, Seasons, Crop, Boundary etc. Prior to uploading prescriptions, it is required to build hierarchy and
+  a prescription_map_id. All prescriptions uploaded to ADMAg are related to farm hierarchy through prescription_map_id. Please refer to
+  https://learn.microsoft.com/en-us/rest/api/data-manager-for-agri/ for more information on ADMAg.
+  - Compute indices using the spyndex python package.
+  - Clip the satellite imagery & sensor samples using farm boundary.
+  - Perform spatial interpolation to find raster pixels within the offset distance from sample location and assign the value of nutrients to group of pixels.
+  - Classify the data based on number of bins.
+  - Train the model using Random Forest classifier.
+  - Predict the nutrients using the satellite imagery.
+  - Generate a shape file using the predicted outputs.
+
 - [`index/index` 📄](workflow_yaml/data_processing/index/index.md): Computes an index from the bands of an input raster.
 
 - [`linear_trend/chunked_linear_trend` 📄](workflow_yaml/data_processing/linear_trend/chunked_linear_trend.md): Computes the pixel-wise linear trend of a list of rasters (e.g. NDVI).
@@ -156,6 +176,8 @@ The inference operation predicts nutrients in soil for the chosen farm boundary.
 
 - [`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/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.
+
 - [`sensor/optimal_locations` 📄](workflow_yaml/farm_ai/sensor/optimal_locations.md): Identify optimal locations by performing clustering operation using Gaussian Mixture model on computed raster indices.
 
 - [`water/irrigation_classification` 📄](workflow_yaml/farm_ai/water/irrigation_classification.md): Develops 30m pixel-wise irrigation probability map.
@@ -169,6 +191,6 @@ The inference operation predicts nutrients in soil for the chosen farm boundary.
 
 - [`driveway_detection` 📄](workflow_yaml/ml/driveway_detection.md): Detects driveways in front of houses.
 
-- [`segment_anything/point_prompt_sam` 📄](workflow_yaml/ml/segment_anything/point_prompt_sam.md): Runs Segment Anything Model (SAM) over a Sentinel-2 raster with points as prompts.
+- [`segment_anything/prompt_segmentation` 📄](workflow_yaml/ml/segment_anything/prompt_segmentation.md): Runs Segment Anything Model over a Sentinel-2 raster with points and/or bounding boxes as prompts.