Update documentation

microsoft · Oct 26, 2023 · afdf80b · afdf80b
1 parent e6d893a
commit afdf80b
Show file tree

Hide file tree

Showing 135 changed files with 1,133 additions and 307 deletions.
diff --git a/_sources/docfiles/markdown/CACHE.md.txt b/_sources/docfiles/markdown/CACHE.md.txt
@@ -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/_sources/docfiles/markdown/NOTEBOOK_LIST.md.txt b/_sources/docfiles/markdown/NOTEBOOK_LIST.md.txt
@@ -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/_sources/docfiles/markdown/TROUBLESHOOTING.md.txt b/_sources/docfiles/markdown/TROUBLESHOOTING.md.txt
@@ -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/_sources/docfiles/markdown/WORKFLOW_LIST.md.txt b/_sources/docfiles/markdown/WORKFLOW_LIST.md.txt
@@ -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.
@@ -156,6 +158,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 +173,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.
 
 
diff --git a/_sources/docfiles/markdown/data_types_diagram/core_types_hierarchy.md.txt b/_sources/docfiles/markdown/data_types_diagram/core_types_hierarchy.md.txt
@@ -2,18 +2,12 @@
 <div class="mermaid">
 
 classDiagram
-  class Dict {
-  }
-  class Type {
-  }
   class AssetVibe {
   }
   class BaseVibe {
   }
   class CarbonOffsetInfo {
   }
-  class Config {
-  }
   class DataSequence {
   }
   class DataSummaryStatistics {
@@ -62,8 +56,6 @@ classDiagram
   GeometryCollection --|> DataVibe
   ProteinSequence --|> DataVibe
   TimeSeries --|> DataVibe
-  TypeDictVibe --|> Dict
-  UnresolvedDataVibe --|> Type
   UnresolvedDataVibe --|> BaseVibe
 
 

diff --git a/_sources/docfiles/markdown/data_types_diagram/json_converter_hierarchy.md.txt b/_sources/docfiles/markdown/data_types_diagram/json_converter_hierarchy.md.txt
@@ -2,11 +2,8 @@
 <div class="mermaid">
 
 classDiagram
-  class JSONEncoder {
-  }
   class DataclassJSONEncoder {
   }
-  DataclassJSONEncoder --|> JSONEncoder
 
 
 </div>
diff --git a/_sources/docfiles/markdown/data_types_diagram/sentinel_hierarchy.md.txt b/_sources/docfiles/markdown/data_types_diagram/sentinel_hierarchy.md.txt
@@ -2,8 +2,6 @@
 <div class="mermaid">
 
 classDiagram
-  class Enum {
-  }
   class StrEnum {
   }
   class BaseVibe {
@@ -64,7 +62,6 @@ classDiagram
   }
   class TiledSentinel1Product {
   }
-  StrEnum --|> Enum
   DataSequence --|> DataVibe
   DataVibe --|> BaseVibe
   CategoricalRaster --|> Raster

diff --git a/_sources/docfiles/markdown/data_types_diagram/utils_hierarchy.md.txt b/_sources/docfiles/markdown/data_types_diagram/utils_hierarchy.md.txt
@@ -2,13 +2,10 @@
 <div class="mermaid">
 
 classDiagram
-  class NamedTuple {
-  }
   class FieldConverter {
   }
   class StacConverter {
   }
-  FieldConverter --|> NamedTuple
 
 
 </div>