From 2692cd69b253a8deb04bf2db1607fcbcd429027b Mon Sep 17 00:00:00 2001
From: Solomon Negusse <solomon.negusse@wri.org>
Date: Wed, 13 Nov 2024 17:05:36 +0300
Subject: [PATCH] consistent and descriptive forest filter query params;
 detailed decoding doc

---
 app/routes/titiler/umd_glad_dist_alerts.py | 21 +++++++++++----------
 1 file changed, 11 insertions(+), 10 deletions(-)

diff --git a/app/routes/titiler/umd_glad_dist_alerts.py b/app/routes/titiler/umd_glad_dist_alerts.py
index 039e5670..a674f9fa 100644
--- a/app/routes/titiler/umd_glad_dist_alerts.py
+++ b/app/routes/titiler/umd_glad_dist_alerts.py
@@ -52,23 +52,24 @@ async def glad_dist_alerts_raster_tile(
         description="Only show alerts until given date.",
     ),
     render_type: RenderType = Query(
-        RenderType.encoded, description="Render true color or encoded tiles"
+        RenderType.encoded,
+        description="Render true color or encoded tiles. Encoded tiles have the alert date and confidence packed in the image RGB channels for front-end interactive use, such as date filtering with supported technologies. Decoding instructions: Alert Date is calculated as `red * 255 + green`, representing days since 2020-12-31. Confidence is calculated as `floor(blue / 100)`, with values of `2` (high) or `1` (low). Intensity is calculated as `mod(blue, 100)`, with a maximum value of `55`.",
     ),
     alert_confidence: Optional[AlertConfidence] = Query(
         AlertConfidence.low,
         description="Show alerts that are at least of this confidence level",
     ),
-    tree_cover_density: Optional[int] = Query(
+    tree_cover_density_threshold: Optional[int] = Query(
         None,
         ge=0,
         le=100,
         description="Alerts in pixels with tree cover density (in percent) below this threshold won't be displayed. `umd_tree_cover_density_2010` is used for this masking.",
     ),
-    tree_cover_height: Optional[int] = Query(
+    tree_cover_height_threshold: Optional[int] = Query(
         None,
         description="Alerts in pixels with tree cover height (in meters) below this threshold won't be displayed. `umd_tree_cover_height_2020` dataset in the API is used for this masking.",
     ),
-    tree_cover_loss_cutoff: Optional[int] = Query(
+    tree_cover_loss_threshold: Optional[int] = Query(
         None,
         ge=2021,
         description="""This filter is to be used in conjunction with `tree_cover_density` and `tree_cover_height` filters to detect only alerts in forests, by masking out pixels that have had tree cover loss prior to the alert.""",
@@ -89,27 +90,27 @@ async def glad_dist_alerts_raster_tile(
         end_date=end_date,
         render_type=render_type,
         alert_confidence=alert_confidence,
-        tree_cover_density_mask=tree_cover_density,
-        tree_cover_height_mask=tree_cover_height,
-        tree_cover_loss_mask=tree_cover_loss_cutoff,
+        tree_cover_density_mask=tree_cover_density_threshold,
+        tree_cover_height_mask=tree_cover_height_threshold,
+        tree_cover_loss_mask=tree_cover_loss_threshold,
     )
 
     filter_datasets = GLOBALS.dist_alerts_forest_filters
-    if tree_cover_density:
+    if tree_cover_density_threshold:
         filter_dataset = filter_datasets["tree_cover_density"]
         with COGReader(
             f"s3://{DATA_LAKE_BUCKET}/{filter_dataset['dataset']}/{filter_dataset['version']}/raster/epsg-4326/cog/default.tif"
         ) as reader:
             dist_alert.tree_cover_density_data = reader.tile(tile_x, tile_y, zoom)
 
-    if tree_cover_height:
+    if tree_cover_height_threshold:
         filter_dataset = filter_datasets["tree_cover_height"]
         with COGReader(
             f"s3://{DATA_LAKE_BUCKET}/{filter_dataset['dataset']}/{filter_dataset['version']}/raster/epsg-4326/cog/default.tif"
         ) as reader:
             dist_alert.tree_cover_height_data = reader.tile(tile_x, tile_y, zoom)
 
-    if tree_cover_loss_cutoff:
+    if tree_cover_loss_threshold:
         filter_dataset = filter_datasets["tree_cover_loss"]
         with COGReader(
             f"s3://{DATA_LAKE_BUCKET}/{filter_dataset['dataset']}/{filter_dataset['version']}/raster/epsg-4326/cog/default.tif"