Merge master

Author: cleherny

README.md

@@ -232,7 +232,11 @@ train_model.py:
     tst: <the COCO JSON file related to the test dataset>
   detectron2_config_file: <the detectron2 configuration file (relative path w/ respect to the working_folder>
   model_weights:
-    model_zoo_checkpoint_url: <e.g. "COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_1x.yaml">
+    pth_file: <path to the model if training is resumed. Defaults to "<log directory>/model_final.pth">
+    model_zoo_checkpoint_url: <zoo model to start training from, e.g. "COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_1x.yaml">
+    init_model_weights: <True or False; if True, the model weights will be initialized to 0 (optional, defaults to False)>
+  resume_training: <True or False; if True, the training is resumed from the final weights saved in the log folder. Defaults to False>
+  data_augmentation: <True or False; if True, apply random adjustment of brightness, contrast, saturation, lightning, and size, plus flip the image horizontally. Defaults to False>
 ```
 
 Detectron2's configuration files are provided in the example folders mentioned here-below. We warn the end-user about the fact that, **for the time being, no hyperparameters tuning is automatically performed**.
@@ -323,7 +327,7 @@ A few examples are provided within the `examples` folder. For further details, w
 * [Segmentation of Border Points based on Analog Cadastral Plans](examples/borderpoints/README.md): multi-class instance segmentation with images from another folder based on a custom grid,
 * [Evolution of Mineral Extraction Sites over the Entire Switzerland](examples/mineral-extrac-sites-detection/README.md): object monitoring with images from an XYZ service,
 * [Swimming Pool Detection over the Canton of Geneva](examples/swimming-pool-detection/GE/README.md): instance segmentation with images from a MIL service,
-* [Swimming Pool Detection over the Canton of Neuchâtel](examples/swimming-pool-detection/NE/README.md): instance segmentation with images from a WMS service.service,
+* [Swimming Pool Detection over the Canton of Neuchâtel](examples/swimming-pool-detection/NE/README.md): instance segmentation with images from a WMS service.
 
 It is brought to the reader attention that the examples are provided with a debug parameter that can be set to `True` for quick tests.
 

examples/anthropogenic-activities/README.md

@@ -1,4 +1,4 @@
-# Example: segmentation of the border points based on the analog cadastral plans
+# Example: segmentation of anthropic soils on historic images
 
 A working setup is provided here to test the multi-class classification and the use of empty tiles, as well as false positive ones.
 It consists of the following elements:
@@ -7,10 +7,10 @@ It consists of the following elements:
 * input data
 * scripts for data preparation and the first step of post-processing
 
-The full project is available is its [own repository](https://github.com/swiss-territorial-data-lab/proj-borderpoints).
+The full project is available is its [own repository](https://github.com/swiss-territorial-data-lab/proj-sda).
 
 
-The **installation** can be carried out by following the instructions in the main readme file. When using Docker, the container must be launched from the repository root folder before running the workflow:
+The **installation** can be carried out by following the instructions [here](../../README.md). When using Docker, the container must be launched from this repository root folder before running the workflow:
 
 ```bash
 $ sudo chown -R 65534:65534 examples
@@ -28,39 +28,53 @@ $ sudo chmod -R a+w examples
 
 ## Data
 
+"[SWISSIMAGE Journey through time](https://www.swisstopo.admin.ch/en/timetravel-aerial-images)" is an annual dataset of aerial images of Switzerland from 1946 to today. These images are downloaded from the geo.admin.ch server using the XYZ connector.
+
 The following datasets are available for this example in the `data` folder:
 
-* images: SWISSIMAGE Journey is an annual dataset of aerial images of Switzerland from 1946 to today. The images are downloaded from the geo.admin.ch server using XYZ connector.
-* empty tiles: tiles without any object of interest added to the training dataset to provide more contextual tiles.
-* FP labels: objects frequently present among false positives, used to include the corresponding tiles in the training.
-* ground truth: labels vectorised by the domain experts.
-    Disclaimer: the ground truth dataset is unofficial and has been produced specifically for the purposes of the project.
+* Empty tiles: tiles without any object of interest can be added to the training dataset to provide more context.
+* False positive (FP) labels: objects frequently present among false positives, used to include the corresponding tiles in the training.
+* Ground truth: labels vectorised by domain experts.
+
+> [!CAUTION]
+> The ground truth dataset is unofficial and has been produced specifically for the purposes of the project.
+    
 
 ## Workflow
 
 The workflow can be executed by running the following list of actions and commands.
 
 Prepare the data:
-```
+
+```bash
 $ python prepare_data.py config_trne.yaml
 $ stdl-objdet generate_tilesets config_trne.yaml
 ```
 
 Train the model:
-```
+
+```bash
 $ stdl-objdet train_model config_trne.yaml
 $ tensorboard --logdir output/trne/logs
 ```
 
-Open the following link with a web browser: `http://localhost:6006` and identify the iteration minimising the validation loss and select the model accordingly (`model_*.pth`) in `config_trne`. The path to the trained model is `output/trne/logs/model_<number of iterations>.pth`, currently `model_0002499.pth` is used. <br>
+Open another shell and launch TensorBoard:
 
-Perform and assess detections:
+```bash
+$ docker compose run --rm -p 6006:6006 stdl-objdet tensorboard --logdir /app/examples/anthropogenic-activities/output/trne/logs --bind_all
 ```
+
+Open the following link with a web browser: `http://localhost:6006` and identify the iteration minimising the validation loss and select the model accordingly (`model_*.pth`) in `config_trne`. The path to the trained model is `output/trne/logs/model_<number of iterations>.pth`, currently `model_0002499.pth` is used.
+
+Perform and assess detections:
+
+```bash
 $ stdl-objdet make_detections config_trne.yaml
 $ stdl-objdet assess_detections config_trne.yaml
 ```
 
 The detections obtained by tiles can be merged when adjacent:
-```
+
+```bash
 $ python merge_detections.py config_trne.yaml
 ```

examples/anthropogenic-activities/config_trne.yaml

@@ -5,7 +5,7 @@ prepare_data.py:
     fp_shapefile: data/FP_labels.gpkg               # FP labels
     # empty_tiles_aoi: data/AoI/<AOI_SHPFILE>           # AOI in which additional empty tiles can be selected. Only one 'empty_tiles' option can be selected  
     # empty_tiles_year: 2023                              # If "empty_tiles_aoi" selected then provide a year. Choice: (1) numeric (i.e. 2020), (2) [year1, year2] (random selection of a year within a given year range) 
-    empty_tiles_shp: data/20240726_EPT.gpkg    # Provided shapefile of selected empty tiles. Only one 'empty_tiles' option can be selected                     
+    empty_tiles_shp: data/20250924_emtpy_tiles.gpkg    # Provided shapefile of selected empty tiles. Only one 'empty_tiles' option can be selected                     
     category_field: Classe
   output_folder: output/trne/
   zoom_level: 16 
@@ -16,11 +16,12 @@ generate_tilesets.py:
     enable: False  # sample of tiles
     nb_tiles_max: 2000
   working_directory: .
+  output_folder: output/trne/
   datasets:
     aoi_tiles: output/trne/tiles.geojson
     ground_truth_labels: output/trne/labels.geojson
-    fp_labels:             # Uncomment if FP shapefile exists in prepare_data.py     
-      fp_shp: output/trne/FP.geojson
+    add_fp_labels:             # Uncomment if FP shapefile exists in prepare_data.py     
+      fp_labels: output/trne/FP.geojson
       frac_trn: 0.7        # fraction of fp tiles to add to the trn dataset, then the remaining tiles will be split in 2 and added to tst and val datasets
     image_source:
       type: XYZ                             # supported values: 1. MIL = Map Image Layer 2. WMS 3. XYZ 4. FOLDER
@@ -30,7 +31,6 @@ generate_tilesets.py:
     tiles_frac: 0.5       # fraction (relative to the number of tiles intersecting labels) of empty tiles to add
     frac_trn: 0.7         # fraction of empty tiles to add to the trn dataset, then the remaining tiles will be split in 2 and added to tst and val datasets
     keep_oth_tiles: False # keep tiles in oth dataset not intersecting oth labels
-  output_folder: output/trne/
   tile_size: 256      # per side, in pixels
   overwrite: True
   n_jobs: 10
@@ -94,21 +94,10 @@ assess_detections.py:
   metrics_method: micro-average   # 1: macro-average ; 2: macro-weighted-average ; 3: micro-average
   # confidence_threshold: 0.05
 
-# Plots (optional)
-result_analysis.py:
-  working_directory: output/trne
-  output_directory: plots
-  detections: tagged_detections.gpkg
-  min_year: 1950
-  max_year: 2023
-  class_dict: {'Activité non agricole': 'Non-agricultural activity', # Provide a customed legend
-                'Mouvement de terrain': 'Land movement'}
-
 # Merge detections across tiles
 merge_detections.py:
   working_directory: output/trne
   output_dir: post_processed
-  labels: labels.geojson
   detections:
     trn: trn_detections_at_0dot05_threshold.gpkg
     val: val_detections_at_0dot05_threshold.gpkg

examples/anthropogenic-activities/data/20240726_EPT.gpkg renamed to examples/anthropogenic-activities/data/20250924_emtpy_tiles.gpkg

@@ -262,7 +262,6 @@ MODEL:
     NAME: SemSegFPNHead
     NORM: GN
     NUM_CLASSES: 54
-  WEIGHTS: https://dl.fbaipublicfiles.com/detectron2/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_1x/137260431/model_final_a54504.pkl
 OUTPUT_DIR: logs
 SEED: 42
 SOLVER:

examples/anthropogenic-activities/detectron2_config.yaml

@@ -35,7 +35,6 @@
     # Load input parameters
     WORKING_DIR = cfg['working_directory']
     OUTPUT_DIR = cfg['output_dir']
-    LABELS = cfg['labels'] if 'labels' in cfg.keys() else None
     DETECTION_FILES = cfg['detections']
 
     DISTANCE = cfg['distance']
@@ -100,8 +99,8 @@
         detections_tiles_join_gdf = gpd.sjoin(tiles_gdf, detections_buffer_gdf, how='left', predicate='contains')
         remove_det_list = detections_tiles_join_gdf.det_id.unique().tolist()
 
-        detections_overlap_tiles_gdf = detections_by_year_gdf[~detections_by_year_gdf.det_id.isin(remove_det_list)].drop_duplicates(subset=['det_id'], ignore_index=True)
         detections_within_tiles_gdf = detections_by_year_gdf[detections_by_year_gdf.det_id.isin(remove_det_list)].drop_duplicates(subset=['det_id'], ignore_index=True)
+        detections_overlap_tiles_gdf = detections_by_year_gdf[~detections_by_year_gdf.det_id.isin(remove_det_list)].drop_duplicates(subset=['det_id'], ignore_index=True)
 
         # Merge polygons within the thd distance
         detections_overlap_tiles_gdf.loc[:, 'geometry'] = detections_overlap_tiles_gdf.buffer(DISTANCE, resolution=2)

examples/anthropogenic-activities/merge_detections.py

@@ -61,7 +61,7 @@
 
     written_files = []
 
-    gt_labels_4326_gdf = ffe.preapre_labels(SHPFILE, CATEGORY, supercategory=SUPERCATEGORY)
+    gt_labels_4326_gdf = ffe.prepare_labels(SHPFILE, CATEGORY, supercategory=SUPERCATEGORY)
 
     label_filepath = os.path.join(OUTPUT_DIR, 'labels.geojson')
     gt_labels_4326_gdf.to_file(label_filepath, driver='GeoJSON')

examples/anthropogenic-activities/prepare_data.py

@@ -258,8 +258,6 @@ MODEL:
     LOSS_WEIGHT: 1.0
     NAME: SemSegFPNHead
     NORM: GN
-    NUM_CLASSES: 54
-  WEIGHTS: https://dl.fbaipublicfiles.com/detectron2/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_1x/137260431/model_final_a54504.pkl
 OUTPUT_DIR: logs
 SEED: 42
 SOLVER:

examples/borderpoints/config/detectron2_config.yaml

@@ -261,8 +261,6 @@ MODEL:
     LOSS_WEIGHT: 1.0
     NAME: SemSegFPNHead
     NORM: GN
-    NUM_CLASSES: 54
-  WEIGHTS: https://dl.fbaipublicfiles.com/detectron2/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_1x/137260431/model_final_a54504.pkl
 OUTPUT_DIR: logs
 SEED: 42
 SOLVER:

examples/mineral-extract-sites-detection/detectron2_config.yaml

@@ -15,7 +15,8 @@
 from shapely.geometry import Polygon
 
 sys.path.insert(0, '../..')
-import helpers.misc as misc
+from helpers.functions_for_examples import format_all_tiles, prepare_labels
+from helpers.misc import format_logger
 from helpers.constants import DONE_MSG
 
 from loguru import logger
@@ -176,70 +177,7 @@ def prepare_labels(shpfile, written_files, prefix=''):
 
     written_files = []
 
-    # Prepare the tiles
-
-    ## Convert datasets shapefiles into geojson format
-    logger.info('Convert the label shapefiles into GeoJSON format (EPSG:4326)...')
-    labels_4326_gdf, written_files = prepare_labels(SHPFILE, written_files)
-    gt_labels_4326_gdf = labels_4326_gdf[['geometry', 'CATEGORY', 'SUPERCATEGORY']].copy()
-
-    # Add FP labels if it exists
-    if FP_SHPFILE:
-        logger.info('Convert the FP label shapefiles into GeoJSON format (EPSG:4326)...')
-        fp_labels_4326_gdf, written_files = prepare_labels(FP_SHPFILE, written_files, prefix='FP_')
-        labels_4326_gdf = pd.concat([labels_4326_gdf, fp_labels_4326_gdf], ignore_index=True)
-
-    # Tiling of the AoI
-    logger.info("- Get the label boundaries")  
-    boundaries_df = labels_4326_gdf.bounds
-    logger.info("- Tiling of the AoI")  
-    tiles_4326_aoi_gdf = aoi_tiling(boundaries_df)
-    tiles_4326_labels_gdf = gpd.sjoin(tiles_4326_aoi_gdf, labels_4326_gdf, how='inner', predicate='intersects')
-
-    # Tiling of the AoI from which empty tiles will be selected
-    if EPT_SHPFILE:
-        EPT_aoi_gdf = gpd.read_file(EPT_SHPFILE)
-        EPT_aoi_4326_gdf = EPT_aoi_gdf.to_crs(epsg=4326)
-        assert_year(labels_4326_gdf, EPT_aoi_4326_gdf, 'empty_tiles', EPT_YEAR)
-        
-        if EPT_TYPE == 'aoi':
-            logger.info("- Get AoI boundaries")  
-            EPT_aoi_boundaries_df = EPT_aoi_4326_gdf.bounds
-
-            # Get tile coordinates and shapes
-            logger.info("- Tiling of the empty tiles AoI")  
-            empty_tiles_4326_all_gdf = aoi_tiling(EPT_aoi_boundaries_df)
-            # Delete tiles outside of the AoI limits 
-            empty_tiles_4326_aoi_gdf = gpd.sjoin(empty_tiles_4326_all_gdf, EPT_aoi_4326_gdf, how='inner', lsuffix='ept_tiles', rsuffix='ept_aoi')
-            # Attribute a year to empty tiles if necessary
-            if 'year' in labels_4326_gdf.keys():
-                if isinstance(EPT_YEAR, int):
-                    empty_tiles_4326_aoi_gdf['year'] = int(EPT_YEAR)
-                else:
-                    empty_tiles_4326_aoi_gdf['year'] = np.random.randint(low=EPT_YEAR[0], high=EPT_YEAR[1], size=(len(empty_tiles_4326_aoi_gdf)))
-        elif EPT_TYPE == 'shp':
-            if EPT_YEAR:
-                logger.warning("A shapefile of selected empty tiles are provided. The year set for the empty tiles in the configuration file will be ignored")
-                EPT_YEAR = None
-            empty_tiles_4326_aoi_gdf = EPT_aoi_4326_gdf.copy()
-
-        # Get all the tiles in one gdf 
-        logger.info("- Concatenate label tiles and empty AoI tiles") 
-        tiles_4326_all_gdf = pd.concat([tiles_4326_labels_gdf, empty_tiles_4326_aoi_gdf])
-    else: 
-        tiles_4326_all_gdf = tiles_4326_labels_gdf.copy()
-
-    # - Remove useless columns, reset feature id and redefine it according to xyz format  
-    logger.info('- Add tile IDs and reorganise the data set')
-    tiles_4326_all_gdf = tiles_4326_all_gdf[['geometry', 'title', 'year'] if 'year' in tiles_4326_all_gdf.keys() else ['geometry', 'title']].copy()
-    tiles_4326_all_gdf.reset_index(drop=True, inplace=True)
-    tiles_4326_all_gdf = tiles_4326_all_gdf.apply(add_tile_id, axis=1)
-
-    # - Remove duplicated tiles
-    tiles_4326_all_gdf.drop_duplicates(['id'], inplace=True)
-
-    nb_tiles = len(tiles_4326_all_gdf)
-    logger.info(f"There were {nb_tiles} tiles created")
+    gt_labels_4326_gdf = prepare_labels(SHPFILE, CATEGORY, supercategory=SUPERCATEGORY)
 
     # Get the number of tiles intersecting labels
     tiles_4326_gt_gdf = gpd.sjoin(tiles_4326_all_gdf, gt_labels_4326_gdf, how='inner', predicate='intersects')