Sync with prod branch

Co-authored-by: Bruno Silva <[email protected]> Co-authored-by: Eduardo Rodrigues <[email protected]> Co-authored-by: Jessica Wolk <[email protected]> Co-authored-by: Naga Bilwanth Gangarapu <[email protected]> Co-authored-by: Rafael Padilha <[email protected]> Co-authored-by: Renato Luiz de Freitas Cunha <[email protected]> Co-authored-by: Rick Gutierrez <[email protected]>
microsoft · Jan 23, 2024 · 522e578 · 522e578
1 parent 725934a
commit 522e578
Show file tree

Hide file tree

Showing 62 changed files with 3,916 additions and 616 deletions.
diff --git a/docs/source/docfiles/markdown/AKS.md b/docs/source/docfiles/markdown/AKS.md
@@ -8,6 +8,58 @@ The primary focus of this guide is to help users understand the structure and
 organization of the Terraform scripts used to create and configure the remote
 cluster and its associated Azure cloud components.
 
+## Requirements
+
+The FarmVibes.AI remote management script works with the assumption that
+whoever is executing it has at least a *Contributor* role in the Azure
+subscription.
+
+The `az` command-line interface is a hard requirement for running the script.
+Please follow the [Azure Command-Line Interface (CLI)
+documentation](https://docs.microsoft.com/cli/azure/) for instructions on how
+to install it. Make sure to install the version appropriate for your
+architecture, otherwise the install process may fail.
+
+### Azure Providers
+
+Since the FarmVibes.AI remote management script needs to provision new
+resources on Azure, it needs access to various [Azure
+Providers](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs).
+The script itself is able to register each required provider. As of the time of
+writing of this document, the required providers are:
+
+ * `Microsoft.DocumentDB`, for provisioning Cosmos DB
+ * `Microsoft.KeyVault`, for managing an Azure KeyVault for managing secrets
+ * `Microsoft.ContainerService`, for managing AKS itself
+ * `Microsoft.Network`, for configuring public IPs and vnets
+ * `Microsoft.Storage`, for provisioning
+   [storage](https://learn.microsoft.com/en-us/azure/storage/) accounts
+ * `Microsoft.Compute`, for provisioning Virtual Machines and Virtual Machines
+   Scale Sets
+
+### CPUs
+
+In the default configuration, your subscription's CPU quota must support at
+least 16 vCPUs in the region you choose. You will also need 12 `Standard DSv3
+Family vCPUs` available. Please follow the [Azure quota increase
+guide](https://learn.microsoft.com/en-us/azure/quotas/quickstart-increase-quota-portal).
+The installer will fail if the quota is not available.
+
+### Setting the subscription
+
+Some Azure users will have access to multiple subscriptions. To list all
+subscriptions you have access to, use the command
+
+```
+az account list
+```
+
+Then, you can set your default subscription with the command
+
+```
+az account set ${YOUR_DESIRED_SUBSCRIPTION_ID}
+```
+
 ## Azure Cloud Components
 
 ![Architecture diagram of the remote FarmVibes.AI configuration](./aks-terraform.svg)
@@ -151,7 +203,11 @@ To create a new remote cluster, you have to provide some required arguments to `
 
 The script will create a new resource group with the specified name, and use it to create the cluster, also creating it if it doesn't exist.
 
-An example creation command is shown below:
+**NOTE**: We recommend you use an empty resource group to create your cluster.
+If you ever need to destroy your cluster, all changes in your subscription will
+be restricted to that resource group.
+
+An example setup command is shown below:
 
 ```bash
 farmvibes-ai remote setup \
@@ -172,3 +228,73 @@ You can use to access the REST API and the FarmVibes.AI client, following the in
 from vibe_core.client import get_default_vibe_client
 client = get_default_vibe_client("remote")
 ```
+
+## Pre-registering providers
+
+As mentioned before, the installer will auto-register each provider
+automatically, but if you'd prefer to pre-register all providers beforehand,
+you can execute the PowerShell script below (which, depending on your security
+settings, might be easier to copy and paste the code in the prompt.)
+
+<details>
+  <summary>PowerShell script example (click to expand)</summary>
+
+```powershell
+# Define the list of providers to register
+$providers = @(
+    "Microsoft.DocumentDB",
+    "Microsoft.KeyVault",
+    "Microsoft.ContainerService",
+    "Microsoft.Network",
+    "Microsoft.Storage",
+    "Microsoft.Compute"
+)
+
+# Initialize arrays for jobs and a hashtable for job-provider mapping
+$jobs = @()
+$jobProviderMap = @{}
+
+# Start a job for each provider to register it
+foreach ($provider in $providers) {
+    $job = Start-Job -ScriptBlock {
+        param($provider)
+        $currentState = az provider show -n $provider --query "registrationState" -o tsv
+
+        if ($currentState -ne "Registered" -and $currentState -ne "Registering") {
+            az provider register --namespace $provider
+        }
+
+        do {
+            $registrationState = az provider show -n $provider --query "registrationState" -o tsv
+            if ($registrationState -ne "Registered") {
+                Start-Sleep -Seconds 10
+            }
+        } while ($registrationState -ne "Registered")
+
+        $provider
+    } -ArgumentList $provider
+
+    $jobs += $job
+    $jobProviderMap[$job.Id] = $provider
+}
+
+# Periodically check the status of each job
+while ($jobs | Where-Object { $_.State -eq 'Running' }) {
+    Clear-Host
+    foreach ($job in $jobs) {
+        $state = $job.ChildJobs[0].JobStateInfo.State
+        $providerName = $jobProviderMap[$job.Id]
+        Write-Host "Provider $providerName is in $state state."
+    }
+    Start-Sleep -Seconds 10
+}
+
+# Retrieve and display the final status of each job, then clean up
+foreach ($job in $jobs) {
+    $providerName = Receive-Job -Job $job -Wait
+    Write-Host "Provider $providerName is now registered."
+    Remove-Job -Job $job
+}
+```
+</details>
+
diff --git a/docs/source/docfiles/markdown/NOTEBOOK_LIST.md b/docs/source/docfiles/markdown/NOTEBOOK_LIST.md
@@ -30,6 +30,13 @@ We organize available notebooks in the following topics:
 - [`Nutrient Heatmap Estimation with ADMAg integration` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/heatmaps/nutrients_using_classification_admag.ipynb)
 
 
+</details>
+<details>
+<summary> BingMaps </summary>
+
+- [`Segment Anything Model Workflow (BingMaps basemap)` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/segment_anything/basemap_segmentation.ipynb)
+
+
 </details>
 <details>
 <summary> Crop Analysis </summary>
@@ -55,11 +62,14 @@ We organize available notebooks in the following topics:
 
 
 </details>
+
 <details>
 <summary> Index Computation </summary>
 
 - [`Crop cycle detection` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/crop_cycles/crop_cycles.ipynb)
 
+- [`Field-level spectral indices` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sentinel/field_level_spectral_indices.ipynb)
+
 - [`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)
@@ -72,7 +82,9 @@ We organize available notebooks in the following topics:
 
 - [`Nutrient Heatmap Estimation with ADMAg integration` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/heatmaps/nutrients_using_classification_admag.ipynb)
 
-- [`Optimal Location` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sensor/optimal_locations.ipynb)
+- [`Optimal Sensor Placement` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sensor/optimal_locations.ipynb)
+
+- [`Optimal Sensor Placement over Segmented Crop Field` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sensor/optimal_locations_segmentation.ipynb)
 
 - [`Spectral indices` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sentinel/spectral_indices.ipynb)
 
@@ -106,7 +118,7 @@ We organize available notebooks in the following topics:
 
 - [`Nutrient Heatmap Estimation with ADMAg integration` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/heatmaps/nutrients_using_classification_admag.ipynb)
 
-- [`Optimal Location` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sensor/optimal_locations.ipynb)
+- [`Optimal Sensor Placement` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sensor/optimal_locations.ipynb)
 
 - [`Weed detection` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/weed_detection/weed_detection.ipynb)
 
@@ -142,15 +154,21 @@ We organize available notebooks in the following topics:
 
 - [`Field boundary segmentation (SAM exploration)` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/segment_anything/sam_exploration.ipynb)
 
-- [`Harvest and germination periods` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/harvest_period/ndvi_summary.ipynb)
+- [`Field-level Irrigation Classification` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/irrigation/field_level_irrigation_classification.ipynb)
 
-- [`Investigating Amazon Rainforest deforestation with SpaceEye` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sentinel/sentinel_spaceeye.ipynb)
+- [`Field-level spectral indices` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sentinel/field_level_spectral_indices.ipynb)
+
+- [`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)
 
-- [`Segment Anything Model Workflow` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/segment_anything/sam_workflow.ipynb)
+- [`Optimal Sensor Placement over Segmented Crop Field` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sensor/optimal_locations_segmentation.ipynb)
+
+- [`Segment Anything Model Workflow (BingMaps basemap)` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/segment_anything/basemap_segmentation.ipynb)
+
+- [`Segment Anything Model Workflow (Sentinel-2)` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/segment_anything/sentinel2_segmentation.ipynb)
 
 - [`Spectral indices` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sentinel/spectral_indices.ipynb)
 
@@ -165,7 +183,15 @@ We organize available notebooks in the following topics:
 
 - [`Field boundary segmentation (SAM exploration)` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/segment_anything/sam_exploration.ipynb)
 
-- [`Segment Anything Model Workflow` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/segment_anything/sam_workflow.ipynb)
+- [`Field-level Irrigation Classification` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/irrigation/field_level_irrigation_classification.ipynb)
+
+- [`Field-level spectral indices` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sentinel/field_level_spectral_indices.ipynb)
+
+- [`Optimal Sensor Placement over Segmented Crop Field` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sensor/optimal_locations_segmentation.ipynb)
+
+- [`Segment Anything Model Workflow (BingMaps basemap)` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/segment_anything/basemap_segmentation.ipynb)
+
+- [`Segment Anything Model Workflow (Sentinel-2)` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/segment_anything/sentinel2_segmentation.ipynb)
 
 
 </details>
@@ -174,6 +200,8 @@ We organize available notebooks in the following topics:
 
 - [`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)
+
 - [`Investigating Amazon Rainforest deforestation with SpaceEye` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sentinel/sentinel_spaceeye.ipynb)
 
 - [`Nutrient Heatmap Estimation - Classification` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/heatmaps/nutrients_using_classification.ipynb)
@@ -182,9 +210,11 @@ We organize available notebooks in the following topics:
 
 - [`Nutrient Heatmap Estimation with ADMAg integration` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/heatmaps/nutrients_using_classification_admag.ipynb)
 
-- [`Optimal Location` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sensor/optimal_locations.ipynb)
+- [`Optimal Sensor Placement` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sensor/optimal_locations.ipynb)
+
+- [`Optimal Sensor Placement over Segmented Crop Field` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sensor/optimal_locations_segmentation.ipynb)
 
-- [`Segment Anything Model Workflow` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/segment_anything/sam_workflow.ipynb)
+- [`Segment Anything Model Workflow (Sentinel-2)` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/segment_anything/sentinel2_segmentation.ipynb)
 
 - [`Spectral indices` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sentinel/spectral_indices.ipynb)
 
@@ -195,6 +225,8 @@ We organize available notebooks in the following topics:
 
 - [`Crop cycle detection` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/crop_cycles/crop_cycles.ipynb)
 
+- [`Field-level spectral indices` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sentinel/field_level_spectral_indices.ipynb)
+
 - [`Investigating Amazon Rainforest deforestation with SpaceEye` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sentinel/sentinel_spaceeye.ipynb)
 
 - [`Timelapse visualization` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sentinel/timelapse_visualization.ipynb)
@@ -214,7 +246,9 @@ We organize available notebooks in the following topics:
 
 - [`Nutrient Heatmap Estimation with ADMAg integration` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/heatmaps/nutrients_using_classification_admag.ipynb)
 
-- [`Optimal Location` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sensor/optimal_locations.ipynb)
+- [`Optimal Sensor Placement` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sensor/optimal_locations.ipynb)
+
+- [`Optimal Sensor Placement over Segmented Crop Field` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sensor/optimal_locations_segmentation.ipynb)
 
 - [`What-if analysis of carbon sequestration` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/carbon/whatif.ipynb)
 
@@ -230,6 +264,8 @@ We organize available notebooks in the following topics:
 <details>
 <summary> Water Management </summary>
 
+- [`Field-level Irrigation Classification` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/irrigation/field_level_irrigation_classification.ipynb)
+
 - [`Irrigation classification` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/irrigation/irrigation_classification.ipynb)
 
 
@@ -271,9 +307,7 @@ We organize available notebooks in the following topics:
 
 - [`Nutrient Heatmap Estimation with ADMAg integration` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/heatmaps/nutrients_using_classification_admag.ipynb)
 
-- [`Optimal Location` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sensor/optimal_locations.ipynb)
-
-- [`Segment Anything Model Workflow` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/segment_anything/sam_workflow.ipynb)
+- [`Optimal Sensor Placement` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sensor/optimal_locations.ipynb)
 
 - [`Spectral indices` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sentinel/spectral_indices.ipynb)
 
@@ -308,6 +342,10 @@ We organize available notebooks in the following topics:
 
 - [`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.
+
+- [`Field-level spectral indices` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sentinel/field_level_spectral_indices.ipynb) : Compute and visualize spectral indices over crop fields segmented from Sentinel-2 and SpaceEye imagery.
+
 - [`Green House Gas fluxes` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/ghg_fluxes/ghg_fluxes.ipynb)  (30s) : Compute GHG emissions and sequestration for a given crop, location and time range.
 
 - [`Harvest and germination periods` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/harvest_period/ndvi_summary.ipynb) : Infer harvest and germination periods from NDVI time series.
@@ -330,9 +368,13 @@ We organize available notebooks in the following topics:
 
 - [`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.
 
-- [`Optimal Location` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sensor/optimal_locations.ipynb) : Helps to find optimal locations using satellite imagery. The optimal locations identified can be used to collect soil properties by installing sensors  or performing other manual operations
+- [`Optimal Sensor Placement` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sensor/optimal_locations.ipynb) : Helps to find optimal sensor placement location using satellite imagery. The optimal locations identified can be used to collect soil properties by installing sensors or performing other manual operations
+
+- [`Optimal Sensor Placement over Segmented Crop Field` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sensor/optimal_locations_segmentation.ipynb) : Segment a field with Segment Anything Model over Sentinel-2 imagery and estimate optimal sensor placement for the segmented region.
+
+- [`Segment Anything Model Workflow (BingMaps basemap)` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/segment_anything/basemap_segmentation.ipynb) : Segment BingMaps basemaps with SAM workflow.
 
-- [`Segment Anything Model Workflow` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/segment_anything/sam_workflow.ipynb) : Segment Sentinel-2 imagery with SAM workflow.
+- [`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 indices` 📓](https://github.com/microsoft/farmvibes-ai/blob/main/notebooks/sentinel/spectral_indices.ipynb) : Compute and visualize spectral indices from Sentinel-2 imagery.
 

diff --git a/docs/source/docfiles/markdown/TROUBLESHOOTING.md b/docs/source/docfiles/markdown/TROUBLESHOOTING.md
@@ -232,7 +232,7 @@ This document compiles the most common issues encountered when installing and ru
   <summary> Adding SAM's ONNX models to the cluster</summary>
 
   Running workflows based on SAM requires the image encoder and prompt encoder/mask decoder to be
-  exported as ONNX models, and added to the cluster. To do so, run the following command:
+  exported as ONNX models, and added to the cluster. To do so, run the following command in the repository root:
   
   ```bash
   python scripts/export_sam_models.py --models <model_types>