#260 update the extract shorelines guide, getting started guide and w…

…hat is in a session guide to explain where the extracted shoreline figures are generated, how downloaded data and sessions are kept track of, and add new figures to show contents of downloaded data and extracted shorelines folders
SatelliteShorelines · Jun 18, 2024 · c17d7a9 · c17d7a9
1 parent 46bed8b
commit c17d7a9
Show file tree

Hide file tree

Showing 4 changed files with 208 additions and 113 deletions.
diff --git a/docs/extract_shorelines.md b/docs/extract_shorelines.md
@@ -85,7 +85,11 @@ If most of your imagery looks like these examples you may need to change your RO
 
 ## Step 4: Examine Shorelines Extracted from 3-5 years of imagery
 
-- Under the sessions directory within the session you created look under `jpg_files\detection`
+- When you click extract shorelines a new directory with the session name you provided will be created at `CoastSeg/sessions`. It will contain a subdirectory for each ROI you selected and within each subdirectory will be all the files generated by extracting shorelines which are detailed in [Extracted Shoreline Session Contents](#extracted-shoreline-session-contents). 
+
+- You can find images that show the extracted shoreline on each image in `coastseg/sessions/<YOUR SESSION NAME>/ROI_ID_NAME/jpg_files/detection` as shown below:
+
+![coastseg/sessions/session/roi/jpg_files/detection](https://github.com/SatelliteShorelines/CoastSeg/assets/61564689/f5be75fb-1c75-46c2-bbec-b9b1e716fea4)
 
 | Description                                                                              | Example Image                                                                                                             | Suggested Adjustment                                                        |
 | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
@@ -123,3 +127,49 @@ Interactively view the extracted shorelines on the map and remove outliers using
 ### YouTube Video
 
 [![Alt text for your video](http://img.youtube.com/vi/WlfC1bukXI0/0.jpg)](http://www.youtube.com/watch?v=WlfC1bukXI0)
+
+
+## Extracted Shoreline Session Contents
+
+A session contains all the files created during the process of extracting shorelines from specific ROIs whose data is stored in `CoastSeg/data`. Each ROI's settings, rasters, imagery, and metadata, generated during the download process, are organized into folders within `CoastSeg/data`, ensuring that the downloaded data remains independent of the extracted shorelines. Each session references the specific ROI(s) in `CoastSeg/data` it was derived from in the `config.json` file. While the structure of a session may vary depending on user actions, such as whether tide correction was applied, it will always contain the files `config_gdf.geojson` and `config.json` because they are needed to reference the downloaded ROI(s)from which the shorelines were extracted.
+
+
+## Location of Sessions
+
+Sessions are saved to `CoastSeg/sessions`. A session contains the all the files related to extract shorelines for a particular set of ROIs in the downloaded data located in `CoastSeg/data`. Each session follows a similar format depending on what actions were taken by the user. For instance, if tide correction was not applied during the session then none of the files with the tidal correction applied will be present.
+
+## Sample Session Structure
+
+Here is a sample session that had 2 ROIs where shorelines were successfully extracted and tide correction was applied to both ROIs.
+
+```
+├── CoastSeg
+|
+|___session
+|    |_ ID_4_datetime11-22-22__11_15_15
+│   |   |_ jpg_files
+│   |   |  |_ detection # this folder contains images of the extracted shorelines overlaid on the original scene
+│   |   |  |  |_ 2023-12-09-18-40-08_L9.jpg   # this is the shoreline extracted from satellite L9 on 2023-12-09 at 18:40:08
+│   |   |  |  |_ <rest of shoreline detection images>
+│   |   |_config.json
+│   |   |_config_gdf.json
+│   |   |_extracted_shorelines_lines.geojson
+│   |   |_extracted_shorelines_points.geojson
+│   |   |_raw_transect_time_series.csv
+│   |   |_raw_transect_time_series_merged.csv
+│   |   |_raw_transect_time_series_points.geojson
+│   |   |_raw_transect_time_series_vectors.geojson
+│   |   |_tidally_corrected_transect_time_series.csv        # this file will only appear if tidal correction was applied
+│   |   |_tidally_corrected_transect_time_series_merged.csv # this file will only appear if tidal correction was applied
+│   |   |_tidally_corrected_transect_time_series_points.geojson # this file will only appear if tidal correction was applied
+│   |   |_tidally_corrected_transect_time_series_vectors.geojson # this file will only appear if tidal correction was applied
+│   |   |_shoreline_settings.json
+│   |   |_transects_cross_distances.json
+│   |   |_transects_settings.json
+│   |   |
+|   |_ ID_3_datetime11-22-22__11_15_15
+│   |   |_ jpg_files
+│   |   |_config.json
+│   |   |_config_gdf.json
+│   |   |_<rest of files>
+```
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -86,11 +86,12 @@ jupyter lab SDS_coastsat_classifier.ipynb
 
 **7.Name the Session**
 
-- Let's call this 'demo_session'
+- Name the session 'demo_session'. This will be the name of the folder saved in `CoastSeg/sessions`.
 
-- This is the name of the folder that will be saved in `CoastSeg/sessions`
+- The folder will contain a subdirectory for each ROI from which shorelines were extracted.
+
+- Keeping sessions and downloaded data separate allows users to create multiple sessions from the same downloaded data, enabling experimentation with different settings.
 
-- It will contain a subdirectory for each ROI that shorelines will be extracted for
 
 ![save_demo_session](https://github.com/SatelliteShorelines/CoastSeg/assets/61564689/4340c734-e20d-4149-89c2-11e73d9905d3)
 
@@ -102,13 +103,19 @@ jupyter lab SDS_coastsat_classifier.ipynb
 
 ![case study 1 preview imagery](https://github.com/SatelliteShorelines/CoastSeg/assets/61564689/db42fee9-682b-4e15-8470-b97a166e42a8)
 
-**9.Download the ROIs**
+**9. Download the ROIs**
+
+- Click the ROIs you want to download on the map (they will turn blue when selected).
+
+- If no transects or reference shorelines are available for the region you have uploaded, follow the guide here.
+
+- NEVER rename your ROIs. This is because CoastSeg keeps track of the filename in the 'config.json' and you won't be able to load it into CoastSeg again if you do. The ROI's ID is the filename, so that information will be lost if you rename it.
 
-- Click the ROIs you want to download on the map ( they will turn blue when selected)
+- The downloaded data can be found in `CoastSeg/data` under a folder with a name in the format `ID_<ROI ID>_datetime<currenttime>`. For example, you can see the JPGs for all the images you downloaded in `CoastSeg/data/ID_<ROI ID>_datetime06-17-24__11_12_40/jpg_files/preprocessed/RGB`.
 
-- If no transects or reference shorelines are available for the region you have uploaded follow the guide here
+- This is example of the RGB imagery from a downloaded ROI. Here you can see the user sorted some of the imagery into a bad folder so it would not be used to extract shorelines. A full tutorial on how to filter bad imagery is available [here](https://satelliteshorelines.github.io/CoastSeg/How-to-Filter-Out-Bad-Imagery/).
+![coastseg/data/roi/](https://github.com/SatelliteShorelines/CoastSeg/assets/61564689/6f357c2e-8cdf-403d-8224-f8ba48946c2c)
 
-- NEVER rename your ROIs this is because CoastSeg keeps track of the filename in the 'config.json' and you won't be able to load it into CoastSeg again if you do. The ROI's ID is the filename so that information will be lost if you rename it.
 
 ![case_study_1_download_roi](https://github.com/SatelliteShorelines/CoastSeg/assets/61564689/1a30f9c7-fc4d-4e34-a57b-055624ff8464)
 
@@ -117,7 +124,12 @@ jupyter lab SDS_coastsat_classifier.ipynb
 
 - Extracting shorelines works by finding the land water interface in the image and drawing a line along it
 
-- A time series of shoreline position along each transect is generated as well
+- A time series of shoreline position along each transect is generated as well.
+
+- You can find images that show the extracted shoreline on each image in `coastseg/sessions/<YOUR SESSION NAME>/ROI_ID_NAME/jpg_files/detection` as shown below:
+
+![coastseg/sessions/session/roi/jpg_files/detection](https://github.com/SatelliteShorelines/CoastSeg/assets/61564689/f5be75fb-1c75-46c2-bbec-b9b1e716fea4)
+
 
 ![shoreline_transect_intersection](https://github.com/SatelliteShorelines/CoastSeg/assets/61564689/e87b8d34-d9a4-4b1e-b3de-8e0be1c16ecd)
 

diff --git a/docs/sessions.md b/docs/sessions.md
@@ -1,7 +1,7 @@
 # What is a Session?
 
 A session is a saved state that CoastSeg was in. A session can be used to load in the ROIs that were downloaded previously or the previously extracted shorelines.
-A session is typically stored as a directory containing a minimum of two files a `config.json` and a `config_gdf.geojson` file that lets you restore the state coastseg was in.
+A session is typically stored as a directory containing a minimum of two files a `config.json` and a `config_gdf.geojson` file that lets you restore the state coastseg was in when the session was created.
 
 ### Where are Sessions Located?
 
@@ -70,99 +70,3 @@ To load config files for ROIs that have been downloaded before go to the `data`
 2. Select a directory from the sessions directory
    ![load_extracted_shorelines_session](https://github.com/SatelliteShorelines/CoastSeg/assets/61564689/4d3ba936-3d86-48e1-9d2d-ea67a355c71d)
 
-## Config.json
-
-Config.json files can be found in session directories as well as within ROI directories within the data directory.
-
-### Sample Config.json in the data directory
-
-The config files are organized into 2 sections:
-
-1. Settings used to download each ROI organized by each ROI's id
-2. Settings that were saved when the ROI was downloaded under the 'settings' section
-
-a. Settings used to download each ROI organized by each ROI's id
-
-- One setting to pay attention to is the `output epsg` this is the CRS the ROI and all its features are re-projected features into and these re-projected features are the ones used to calculate the shoreline transect intersections.
-
-- The following settings are associated with ROI 0:
-  - ROI 0 has imagery for dates "2018-01-01" - "2019-01-01" and it was saved to the `ID_0_datetime03-22-23__07_29_15` directory at
-    `C:\\1_CoastSeg\\1_official_CoastSeg_repo\\CoastSeg\\data`.
-
-```
-{
-    "0": {
-        "dates": [
-            "2018-01-01",
-            "2019-01-01"
-        ],
-        "sitename": "ID_0_datetime03-22-23__07_29_15",
-        "polygon": [
-            [
-                [
-                    -75.75713505156588,
-                    36.189897585260795
-                ],
-                [
-                    -75.7514757042764,
-                    36.17420897122136
-                ],
-                [
-                    -75.74012332310643,
-                    36.176873810012815
-                ],
-                [
-                    -75.74578267039591,
-                    36.191909415885604
-                ],
-                [
-                    -75.75713505156588,
-                    36.189897585260795
-                ]
-            ]
-        ],
-        "roi_id": "0",
-        "sat_list": [
-            "L5",
-            "L7",
-            "L8"
-        ],
-        "landsat_collection": "C02",
-        "filepath": "C:\\1_CoastSeg\\1_official_CoastSeg_repo\\CoastSeg\\data"
-    },
-    "roi_ids": [
-        "0"
-    ],
-    "settings": {
-        "landsat_collection": "C02",
-        "dates": [
-            "2018-01-01",
-            "2019-03-01"
-        ],
-        "sat_list": [
-            "L5",
-            "L7",
-            "L8"
-        ],
-        "cloud_thresh": 0.68,
-        "dist_clouds": 100,
-        "output_epsg": 32618,
-        "check_detection": false,
-        "adjust_detection": false,
-        "save_figure": true,
-        "min_beach_area": 2100,
-        "min_length_sl": 200,
-        "cloud_mask_issue": false,
-        "sand_color": "default",
-        "pan_off": "False",
-        "max_dist_ref": 396,
-        "along_dist": 25,
-        "min_points": 3,
-        "max_std": 15.0,
-        "max_range": 30.0,
-        "min_chainage": -100.0,
-        "multiple_inter": "auto",
-        "prc_multiple": 0.1
-    }
-}
-```