Merge pull request #175 from wri/field-name-updates

consistent and descriptive forest filter query params; detailed decod…

app/routes/titiler/umd_glad_dist_alerts.py

@@ -52,26 +52,40 @@ 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, confidence and intensity (value for use in alpha/transparency channel to fade out isolated alert pixels at low zoom levels) "
+            "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`. "
+            "For example, a pixel RGB value of `(3, 26, 255)` would decode to: "
+            "**alert date**: `3 * 255 + 26 = 791` (or 2023-03-02), "
+            "**confidence**: `floor(255, 100) = 2` (high), and "
+            "**intensity**: `mod(255, 100) = 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.",
+        description="Show alerts in pixels with tree cover density (in percent) greater than or equal to this threshold. `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.",
+        description="Show alerts in pixels with tree cover height (in meters) greater than or equal to this threshold. `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.""",
+        description="""This filter is to be used in conjunction with `tree_cover_density_threshold` and `tree_cover_height_threshold` filters to detect only alerts in forests, by masking out pixels that have had tree cover loss prior to the alert.""",
     ),
 ) -> Response:
     """UMD GLAD DIST alerts raster tiles."""
@@ -89,27 +103,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"