Put images in lfs

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text

app/Home.py

@@ -26,8 +26,77 @@ st.markdown("# Home")
 
 # First section
 st.markdown("## Introduction")
-st.markdown("TODO: new introduction")
+st.markdown(
+    """
+    The goal of this Flood Mapping Tool is to provide visual insight into the extent of flood events.
+    This tool does not produce its own forecasts; it leverages the flood forecasts created
+    by the GloFAS Global Flood Monitoring (GFM) tool and aims to make them conveniently accessible.
+    GFM uses satellite data from Sentinel-1 as the basis of its forecasts. More information on GFM
+    and Sentinel-1 can be found on the Methodology page.
+
+    How to use the Areas Of Interest and Flood Analysis pages is described below. The image below shows what
+    you can expect a typical usage of the app to look like.
+    """
+)
+
+st.image("app/img/application_example.png")
 
 # Second section
 st.markdown("## How to use the tool")
-st.markdown("TODO: new how to use the tool")
+st.markdown("### Areas Of Interest")
+st.markdown(
+    """
+    Because GFM internally works with Areas Of Interest (AOIs) our Flood Mapping Tool does as well.
+    An AOI is basically the rectangular bounding box within which you will want to analyze floods.
+    AOIs are shared among all users of the tool. If you create or delete an AOI, you will create or delete it
+    for all users, so keep that in mind.
+
+    There are three options on the Areas Of Interest page:
+    - **See Areas**: You will see all AOIs that are already available in the tool, created by you or other users.
+    When you hover over them you will see its name, which can be used to select it on the Flood Analysis page.
+    - **Create New Area**: You can create a new AOI. To create a new area do the following:
+        - Please first check whether an AOI that covers the area you are interested in exists already using "See Areas"
+        - Find the location on the map either by zooming to it or by using the looking glass icon to search for a location and jump to it
+        - Click the square icon, then hold down you mouse button and drag a rectangle shape on the screen
+        - If you are unhappy with the shape, click the trash bin icon and then your shape to remove it and start again
+        - If you are happy with the shape give it a (unique) name and hit the Save Area button
+        - Saving can take up to minute, it is externally saved to GFM which takes some time 
+    - **Delete Area**: Select an area by name and hit the Delete button to delete it. This will not delete
+    the related flood products (see next section), only the AOI.
+    """
+)
+st.markdown("### Flood Analysis")
+st.markdown(
+    """
+    The flood analysis page is used to analyze the forecasted extent of floods. It is a forecast because the
+    floods shown are the result of a forecasting model based on satellite data, as described on the Methodology page.
+    They are forecasts of floods in the past though, it is the likely extent of a flood at the selected date and time.
+    The tool does not forecast into the future.
+
+    We will define a couple of terms you will see on this page first and then visually show how to use the page.
+
+    - **AOI**: Area Of Interest as described in the previous section.
+    - **Sentinel Footprint**: The bounding box of the Sentinel-1 satellite image. Floods are retrieved within the footprint.
+    This will be a rectangle but it can be at an angle depending on the orbit path of the satellite. It is possible
+    that a footprint only covers part of your AOI, so it is displayed to show you for which part of the AOI
+    information is available.
+    - **Product**: As described on the Methodology page this application shows flood extents forecasted by GFM.
+    GFM offers their forecasts as products so we use the same terminology. A product contains the flood extents
+    within a specific Sentinel Footprint, as described above, on a specific date and time, the time when the
+    Sentinel measurements were taken.
+    - **Product Time Group**: Sometimes your AOI will be large enough to have multiple products associated with it
+    with timestamps just a couple seconds apart. This happens because the satellite first collected data for
+    the first product and a few seconds later created the second product adjacent to it. In this case we group
+    the products together and label them with the first timestamp of the group. In this case you can possibly see
+    a more oddly shaped footprint, because it is multiple nearby footprints stitched together. 
+
+    Using the page is more easily described visually. Below are some screenshots of the page with how-to-use
+    descriptions in red.
+    """
+)
+
+st.image("app/img/flood_analysis_doc1.png")
+st.image("app/img/flood_analysis_doc2.png")
+st.image("app/img/flood_analysis_doc3.png")
+st.image("app/img/flood_analysis_doc4.png")
+st.image("app/img/flood_analysis_doc5.png")

app/pages/{0_🌍_AOIs.py → 0_🌍_Areas_Of_Interest.py}

@@ -21,7 +21,7 @@ toggle_menu_button()
 add_about()
 
 # Page title
-st.markdown("# AOIs")
+st.markdown("# Areas Of Interest")
 
 # Set page style
 set_tool_page_style()

app/pages/{1_💧_Flood_extent_analysis.py → 1_💧_Flood_Analysis.py}

@@ -58,13 +58,13 @@ def on_area_selector_change():
 
 # Contains AOI selector
 with col1:
-    selected_area_name_id = st.selectbox(
-        "Select saved AOI",
-        options=[aoi["name_id_preview"] for aoi in aois.values()],
+    selected_area_name = st.selectbox(
+        "Select saved area (AOI)",
+        options=[aoi["name"] for aoi in aois.values()],
         on_change=on_area_selector_change,
     )
 
-    selected_area_id = get_aoi_id_from_selector_preview(aois, selected_area_name_id)
+    selected_area_id = get_aoi_id_from_selector_preview(aois, selected_area_name)
 
 # Contain datepickers
 with col2:
@@ -86,7 +86,7 @@ with col4:
     it will not trigger any product downloads.
     """,
     )
-    show_available_products = st.button("Show GFM products")
+    show_available_products = st.button("Show available products")
 
 # If button above is triggered, get products from GFM
 # Then save all products to the session state and rerun the app to display them
@@ -166,45 +166,49 @@ with row_buttons:
 
 # Contains the "Download Products" button
 with below_checkbox_col1:
-    st.text(
-        "Button info",
-        help=""
-        """
-    Will download the selected products from GFM to the Floodmap app
-    (click "Show available products" first if there are none).
-    Products that show that they have already been downloaded can be left checked,
-    they will be skipped.
-    """,
-    )
-    download_products = st.button("Download to Floodmap")
-
-    # If the button is clicked download all checked products that have not been downloaded yet
-    if download_products:
-        index_df = hf_utils.get_geojson_index_df()
-        # Get selected time groups from the table
-        selected_time_groups = product_groups_st_df[product_groups_st_df["Check"]][
-            "Product time"
-        ].tolist()
-
-        # For each selected time group
-        for time_group in selected_time_groups:
-            # Get all products for this time group
-            products_in_group = [
-                p
-                for p in st.session_state["all_products"]
-                if p["product_time_group"] == time_group
-            ]
-
-            # Download each product in the group that hasn't been downloaded yet
-            for product_to_download in products_in_group:
-                if product_to_download["product_id"] not in index_df["product"].values:
-                    with st.spinner(
-                        f"Getting GFM files for {product_to_download['product_time']}, this may take a couple of minutes"
+    if st.session_state["all_products"]:
+        st.text(
+            "Button info",
+            help=""
+            """
+        Will download the selected products from GFM to the Floodmap app
+        (click "Show available products" first if there are none).
+        Products that show that they have already been downloaded can be left checked,
+        they will be skipped.
+        """,
+        )
+        download_products = st.button("Download product to tool")
+
+        # If the button is clicked download all checked products that have not been downloaded yet
+        if download_products:
+            index_df = hf_utils.get_geojson_index_df()
+            # Get selected time groups from the table
+            selected_time_groups = product_groups_st_df[product_groups_st_df["Check"]][
+                "Product time"
+            ].tolist()
+
+            # For each selected time group
+            for time_group in selected_time_groups:
+                # Get all products for this time group
+                products_in_group = [
+                    p
+                    for p in st.session_state["all_products"]
+                    if p["product_time_group"] == time_group
+                ]
+
+                # Download each product in the group that hasn't been downloaded yet
+                for product_to_download in products_in_group:
+                    if (
+                        product_to_download["product_id"]
+                        not in index_df["product"].values
                     ):
-                        gfm.download_flood_product(
-                            selected_area_id, product_to_download
-                        )
-        st.rerun()
+                        with st.spinner(
+                            f"Getting GFM files for {product_to_download['product_time']}, this may take a couple of minutes"
+                        ):
+                            gfm.download_flood_product(
+                                selected_area_id, product_to_download
+                            )
+            st.rerun()
 
 # For all the selected products add them to the map if they are available
 feature_groups = []
@@ -309,7 +313,7 @@ with col2_1:
         <div style="display: flex; align-items: center; gap: 20px;">
             <div style="display: flex; align-items: center;">
                 <div style="width: 20px; height: 20px; background:  rgba(51, 136, 255, .2); border: 1px solid #3388ff;"></div>
-                <div style="margin-left: 5px;">AOI</div>
+                <div style="margin-left: 5px;">Area Of Interest</div>
             </div>
             {flood_part_of_legend}
         </div>

app/pages/{2_📖_Documentation.py → 2_📖_Methodology.py}

@@ -26,7 +26,36 @@ st.markdown("# Documentation")
 # First section
 st.markdown("## Methodology")
 st.markdown(
-    "TODO: new documentation, only kept in Sentinel 1 section unchanged from the Mapaction tool"
+    """
+    This tool does not produce its own forecasts; it leverages the flood forecasts created
+    by the GloFAS Global Flood Monitoring tool and aims to make them conveniently accessible.
+
+    The GFM products are generated using flood detection algorithms applied to Sentinel-1 satellite data,
+    which captures radar imagery in all weather conditions. Sentinel-1 data,
+    acquired in Interferometric Wide-swath mode and VV-polarization, is preprocessed into Analysis-Ready Data
+    (ARD) with a 10x10 m pixel resolution. Three flood detection algorithms are then run in parallel on
+    this ARD:
+
+    - **HASARD (by LIST)**: Uses image comparison and statistical modeling to detect changes in
+      flood-related signals.
+    - **Alg2 (by DLR)**: Applies fuzzy logic and hierarchical thresholding to classify flooded areas.
+    - **Alg3 (by TUW)**: Leverages long-term signal history and statistical modeling for efficient
+      global flood mapping.
+
+    Each algorithm independently classifies flooded pixels, and their results are
+    combined into a consensus map. A pixel is marked as flooded if at least two of the three algorithms
+    agree. This ensemble approach improves accuracy and ensures near-real-time flood monitoring globally.
+
+    Detailed documentation on the methodology is available on the GloFAS
+    website: https://global-flood.emergency.copernicus.eu/technical-information/glofas-gfm/
+
+    The GloFAS documentation mentions 11 products that are published. The products used in this tool are 
+
+    - **The observed flood extent**: these are the floods shown in red when analyzing floods on the
+    "Flood Analysis" page
+    - **The Sentinel-1 footprint**: this is the bounding box of the Sentinel-1 satellite image that contains the
+    flood, shown in yellow when analyzing floods
+    """
 )
 
 
@@ -34,37 +63,13 @@ st.markdown(
 st.markdown("## Radar imagery for flood detection")
 st.markdown(
     """
-    While there are multiple change detections techniques for radar imagery,
-    the one used by Sentinel-1 is one of the simplest. Active radar satellites
-    produce active radiation directed at the land, and images are formed as a
-    function of the time it takes for that radiation to reach back to the
-    satellite. Because of this, radar systems are side-looking (otherwise
-    radiation from multiple areas would reach back at the same time).  To be
-    detected and imaged, radiation needs to be scattered back, but not all
-    surfaces are equally able to scatter back, and that ability is also
-    influenced by the radiation's wavelength (shorter wavelengths are better at
-    detecting smaller objects, while longer wavelengths allow penetration,
-    which is good for forest canopies for example, and biomass studies).
-    Sentinel-1 satellites are C-band (~ 6 cm).<br><br>
-    Water is characterised by a mirror-like reflection mechanism, meaning that
-    no or very little radiation is scattered back to the satellite, so pixels
-    on the image will appear very dark. This very simple change detection takes
-    a "before" image, and looks for drops in intensity, dark spots, in the
-    "after" image.<br><br>
+    As described above, GFM uses Sentinel-1 data as the basis for its flood forecast.
     Sentinel-1 data is the result of measurements from a constellation of two
     satellites, assing over the same areas following the same orbit on average
-    every 6 days. On Google Earth Engine, the processing level is Ground Range
-    Detected (GRD), meaning that it has been detected, multi-looked and
-    projected to ground range using an Earth ellipsoid model. GRD products
-    report on intensity of radiation, but have lost the phase and amplitude
-    information which is needed for other applications (interferometry for
-    example). These satellites emits in different polarizations, and can
-    acquire both single horizonal or vertical, or dual polarizations. Flood
-    water is best detected by using VH (vertical transmit and horizontal
-    receive), although VV (vertical transmit and vertical receive) can be
-    effective to identify partially submerged features. This tool uses VH
-    polarization. Figure 2 shows an overview of the Sentinel-1 observation
+    every 6 days. The figure below shows an overview of the Sentinel-1 observation
     plan, where pass directions and coverage frequencies are highlighted.
+    More detailed documentation on Sentinel-1 can be found on the Copernicus website:
+    https://sentiwiki.copernicus.eu/web/sentinel-1
     """,
     unsafe_allow_html=True,
 )
@@ -74,13 +79,3 @@ st.image(
     "%s" % params["url_sentinel_img"],
     width=1000,
 )
-st.markdown(
-    """
-        <p style="font-size:%s;">
-            Figure 2. Overview of the Sentinel-1 observation plan (<a href=
-            '%s'>source</a>).
-        </p>
-        """
-    % (params["docs_caption_fontsize"], params["url_sentinel_img_location"]),
-    unsafe_allow_html=True,
-)

app/src/config_parameters.py

@@ -8,7 +8,7 @@ params = {
         "Daniele": "[email protected]",
     },
     # Urls
-    "url_github_repo": "https://github.com/mapaction/flood-extent-tool",
+    "url_github_repo": "https://github.com/rodekruis/flood-mapping-tool",
     "url_sentinel_dataset": (
         "https://developers.google.com/earth-engine/datasets/catalog/COPERNICUS_S1_GRD"
     ),

app/src/utils.py

@@ -10,9 +10,9 @@ from src import hf_utils
 from src.config_parameters import params
 
 
-def get_aoi_id_from_selector_preview(all_aois, name_id_preview):
+def get_aoi_id_from_selector_preview(all_aois, name):
     for aoi_id, aoi in all_aois.items():
-        if aoi["name_id_preview"] == name_id_preview:
+        if aoi["name"] == name:
             return aoi_id
 
 
@@ -111,11 +111,10 @@ def add_about():
         None
     """
     # About textbox
-    st.sidebar.markdown("## About")
+    st.sidebar.markdown("## Source Code")
     st.sidebar.markdown(
         f"""
         <p>
-            Todo: general about stuff <br />
             <a href='{params["url_github_repo"]}'>
             Github Repo</a>
         </p>