microsoft · renatolfc · Apr 5, 2024 · Oct 26, 2023 · Jan 23, 2024 · Feb 8, 2024
diff --git a/SUPPORT.md b/SUPPORT.md
@@ -2,15 +2,16 @@
 
 ## How to file issues and get help  
 
-This project uses GitHub Issues to track bugs and feature requests. Please search the existing 
-issues before filing new issues to avoid duplicates.  For new issues, file your bug or 
+This project uses GitHub Issues to track bugs and feature requests. Please search the existing
+issues before filing new issues to avoid duplicates.  For new issues, file your bug or
 feature request as a new Issue.
 
 For help and questions about using this project, please reach out to the team at farmvibes at microsoft.com.
 
 ## Troubleshooting
 
 A list of common issues and their resolution can be found in the [troubleshooting documentation](https://microsoft.github.io/farmvibes-ai/docfiles/markdown/TROUBLESHOOTING.html).
+We also provide a current list of [known issues on our GitHub](https://github.com/microsoft/farmvibes-ai/labels/known%20issues) that are actively being worked on.
 
 ## Microsoft Support Policy  
 

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -22,6 +22,7 @@
     "sphinxcontrib.mermaid",
     "myst_parser",
     "sphinx_autodoc_typehints",
+    "sphinxcontrib.openapi",
 ]
 
 autosummary_generate = True

diff --git a/docs/source/docfiles/code/vibe_core_client/client.md b/docs/source/docfiles/code/vibe_core_client/client.md
@@ -4,6 +4,7 @@
 .. automodule:: vibe_core.client
    :members:
    :show-inheritance:
+   :private-members: _form_payload
 
 .. autosummary::
    :toctree: _autosummary

diff --git a/docs/source/docfiles/markdown/NOTEBOOK_LIST.md b/docs/source/docfiles/markdown/NOTEBOOK_LIST.md
@@ -61,6 +61,19 @@ We organize available notebooks in the following topics:
 - [`Crop land segmentation (4/4) - inference` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/crop_segmentation/04_inference.ipynb)
 
 
+</details>
+<details>
+<summary> Deforestation </summary>
+
+- [`Detecting Forest Changes` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/forest/forest_change_detection.ipynb)
+
+- [`Download ALOS forest extent maps` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/forest/download_alos_forest_map.ipynb)
+
+- [`Download Glad Forest Map` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/forest/download_glad_forest_map.ipynb)
+
+- [`Download Global Forest Change (Hansen) maps.` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/forest/download_hansen_forest_map.ipynb)
+
+
 </details>
 <details>
 <summary> Index Computation </summary>
@@ -151,6 +164,14 @@ We organize available notebooks in the following topics:
 
 - [`Crop land segmentation (4/4) - inference` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/crop_segmentation/04_inference.ipynb)
 
+- [`Detecting Forest Changes` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/forest/forest_change_detection.ipynb)
+
+- [`Download ALOS forest extent maps` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/forest/download_alos_forest_map.ipynb)
+
+- [`Download Glad Forest Map` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/forest/download_glad_forest_map.ipynb)
+
+- [`Download Global Forest Change (Hansen) maps.` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/forest/download_hansen_forest_map.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)
@@ -239,6 +260,14 @@ We organize available notebooks in the following topics:
 
 - [`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)
 
+- [`Detecting Forest Changes` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/forest/forest_change_detection.ipynb)
+
+- [`Download ALOS forest extent maps` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/forest/download_alos_forest_map.ipynb)
+
+- [`Download Glad Forest Map` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/forest/download_glad_forest_map.ipynb)
+
+- [`Download Global Forest Change (Hansen) maps.` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/forest/download_hansen_forest_map.ipynb)
+
 - [`Green House Gas fluxes` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/ghg_fluxes/ghg_fluxes.ipynb)
 
 - [`Nutrient Heatmap Estimation - Classification` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/heatmaps/nutrients_using_classification.ipynb)
@@ -341,6 +370,14 @@ We organize available notebooks in the following topics:
 
 - [`Crop land segmentation (4/4) - inference` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/crop_segmentation/04_inference.ipynb) : Infer crop land segmentation for new regions with a trained model.
 
+- [`Detecting Forest Changes` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/forest/forest_change_detection.ipynb) : Helps users to detect forest changes
+
+- [`Download ALOS forest extent maps` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/forest/download_alos_forest_map.ipynb) : This notebook downloads the ALOS (Advanced Land Observing Satellite) forest extent maps
+
+- [`Download Glad Forest Map` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/forest/download_glad_forest_map.ipynb) : This notebook downloads the Global Land Analysis (GLAD) forest extent maps.
+
+- [`Download Global Forest Change (Hansen) maps.` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/forest/download_hansen_forest_map.ipynb) : This notebook contains functions to download and process the Global Forest Change (Hansen) maps.
+
 - [`Field boundary segmentation (SAM exploration)` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/segment_anything/sam_exploration.ipynb) : Segment Anything Model exploration over FarmVibes.AI data to segment crop field boundaries.
 
 - [`Field-level Irrigation Classification` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/irrigation/field_level_irrigation_classification.ipynb) : Estimate an irrigation probability map over crop fields segmented with Segment Anything Model.

diff --git a/docs/source/docfiles/markdown/QUICKSTART.md b/docs/source/docfiles/markdown/QUICKSTART.md
@@ -111,3 +111,6 @@ that FarmVibes.AI and the python client are working properly.
 For more information on how to execute workflows, please take a look at our
 [client guide](./CLIENT.md). For information on any issues running the cluster, including on
 how to re-start it after a machine reboot, take a look at our [troubleshoot guide](./TROUBLESHOOTING.md).
+If you do not find the information you are looking for, please reach out to the team by opening
+an issue on our [GitHub repository](https://github.com/microsoft/farmvibes-ai/issues) or browsing
+through our [known issues](https://github.com/microsoft/farmvibes-ai/labels/known%20issues).
diff --git a/docs/source/docfiles/markdown/REST_API.md b/docs/source/docfiles/markdown/REST_API.md
@@ -0,0 +1,232 @@
+# REST API
+
+Once the FarmVibes.AI cluster is up and running, you can interact with it using the REST API, which provides a set of endpoints that allow you to list and describe workflows, as well as manage workflow runs.
+The REST API is available at the URL and port specified during cluster creation, and its address is printed in the terminal once the setup is complete. You can also check the address by running the following command in the terminal:
+
+```bash
+$ farmvibes-ai <local | remote> status
+2024-01-01 00:00:00,000 - INFO    - Cluster farmvibes-ai-username is running with 1 servers and 0 agents.
+2024-01-01 00:00:00,001 - INFO    - Service url is http://ip.address:port
+```
+
+## Interacting with the API
+
+The API is accessible from the [FarmVibes.AI Python client](https://microsoft.github.io/farmvibes-ai/docfiles/markdown/CLIENT.html), which provides an interface to interact with the cluster, list workflows, and manage workflow runs.
+Alternativelly, interacting with the API can be done using any tool that can send HTTP requests, such as `curl` or [Bruno](https://www.usebruno.com/).
+
+For example, to list the available workflows, you can use the following command:
+
+```bash
+$ curl -X GET http://localhost:31108/v0/workflows
+```
+
+Which will return the following list:
+
+```
+["helloworld","farm_ai/land_degradation/landsat_ndvi_trend","farm_ai/land_degradation/ndvi_linear_trend", ...]
+```
+
+For submiting a run of a specific workflow, we need to pass a JSON with the run configuration
+(i.e., workflow name, input geometry and time range, workflow parameters, etc) as the body of the
+request. For example, we can use the following command to create a `helloworld` workflow run:
+
+```bash
+$ curl -X POST -H "Content-Type: application/json" -d <JSON>
+```
+
+Replacing the body of the request `<JSON>` with the following:
+
+```json
+{
+  "name": "Hello!",
+  "workflow": "helloworld",
+  "parameters": null,
+  "user_input": {
+    "start_date": "2020-05-01T00:00:00",
+    "end_date": "2020-05-05T00:00:00",
+    "geojson": {
+      "features": [
+        {
+          "geometry": {
+            "type": "Polygon",
+            "coordinates": [
+              [
+                [
+                  -119.14896203939314,
+                  46.51578909859286
+                ],
+                [
+                  -119.14896203939314,
+                  46.37578909859286
+                ],
+                [
+                  -119.28896203939313,
+                  46.37578909859286
+                ],
+                [
+                  -119.28896203939313,
+                  46.51578909859286
+                ],
+                [
+                  -119.14896203939314,
+                  46.51578909859286
+                ]
+              ]
+            ]
+          },
+          "type": "Feature"
+        }
+      ],
+      "type": "FeatureCollection"
+    }
+  }
+}
+```
+
+To help in understanding the expected format and structure of the json in our requests, we provide in
+our Python client the `_form_payload` method ([`vibe_core.client.FarmvibesAiClient._form_payload`](https://microsoft.github.io/farmvibes-ai/docfiles/code/vibe_core_client/client.html#vibe_core.client.FarmvibesAiClient._form_payload)) that can be used to
+generate the request payload for a given run configuration. For example, the following code could
+be used to obtain the json above for the helloworld workflow:
+
+```python
+from vibe_core.client import get_default_vibe_client
+import shapely.geometry as shpg
+from datetime import datetime
+
+client = get_default_vibe_client()
+
+geom = shpg.Point(-119.21896203939313, 46.44578909859286).buffer(.07, cap_style=3)
+time_range = (datetime(2020, 5, 1), datetime(2020, 5, 5))
+
+payload = client._form_payload("helloworld", None, geom, time_range, None,"Hello!")
+```
+
+Another example, considering the `farm_ai/segmentation/segment_s2` workflow run submited in the
+[Sentinel-2 Segmentation notebook](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/segment_anything/sentinel2_segmentation.ipynb), would be:
+
+```python
+payload = client._form_payload("farm_ai/segmentation/segment_s2", None, None, None, {"user_input": roi_time_range, "prompts": geom_collection},"SAM segmentation") 
+```
+
+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"
+    }
+  }
+}
+```
+
+For more information about the `_form_payload` method, please refer to the [FarmVibes.AI Python client documentation](https://microsoft.github.io/farmvibes-ai/docfiles/code/vibe_core_client/client.html#vibe_core.client.FarmvibesAiClient._form_payload).
+
+## Endpoints
+
+We provide below a list of the available endpoints and their descriptions.
+
+-----------------------------
+
+```{eval-rst}
+.. openapi:: ../openapi.json
+    :examples:
+    :format: markdown
+```
diff --git a/docs/source/docfiles/markdown/TROUBLESHOOTING.md b/docs/source/docfiles/markdown/TROUBLESHOOTING.md
@@ -1,6 +1,8 @@
 # Troubleshooting
 
 This document compiles the most common issues encountered when installing and running FarmVibes.AI platform, grouped into broad categories.
+Besides the issues listed here, we also collect a list of [known issues on our GitHub repository](https://github.com/microsoft/farmvibes-ai/labels/known%20issues)
+that are currently being addressed by the development team.
 
 - **Package installation:**
 
@@ -224,6 +226,13 @@ This document compiles the most common issues encountered when installing and ru
 
   </details>
 
+  <details>
+  <summary> Workflow run monitor table not rendering inside notebook</summary>
+
+  Make sure to have the `ipywidgets` [package](https://pypi.org/project/ipywidgets/) installed in your environment.
+
+  </details>
+
 <br>
 
 - **Segment Anything Model (SAM):**

diff --git a/docs/source/docfiles/markdown/WORKFLOWS.md b/docs/source/docfiles/markdown/WORKFLOWS.md
@@ -7,6 +7,7 @@ We group FarmVibes.AI workflows in the following categories:
 This includes raw data sources (e.g., Sentinel 1 and 2, LandSat, CropDataLayer) as well as the SpaceEye cloud-removal model;
 - **Data Processing**: workflows that transform data into different data types (e.g., computing NDVI/MSAVI/Methane indexes, aggregating mean/max/min statistics of rasters, timeseries aggregation);
 - **FarmAI**:  composed workflows (data ingestion + processing) whose outputs enable FarmAI scenarios (e.g., predicting conservation practices, estimating soil carbon sequestration, identifying methane leakage);
+- **ForestAI**: composed workflows (data ingestion + processing) whose outputs enable ForestAI scenarios (e.g., detecting forest change, estimating forest extent);
 - **ML**: machine learning-related workflows to train, evaluate, and infer models within the FarmVibes.AI platform (e.g., dataset creation, inference);
 
 For a list of all available workflows within the FarmVibes.AI platform, please