Update README.md

README.md

@@ -17,19 +17,19 @@ model-index:
     metrics:
     - name: mIoU
       type: mIoU
-      value: 54.7168
+      value: 58.63
     - name: Overall Accuracy
       type: OA
       value: 76.3711
     - name: Fscore
       type: Fscore
-      value: 67.6063
+      value: 72.4353
     - name: Precision
       type: Precision
-      value: 69.3481
+      value: 74.3015
     - name: Recall
       type: Recall
-      value: 67.6565
+      value: 72.4891
       
     - name: IoU Buildings
       type: IoU
@@ -78,6 +78,7 @@ pipeline_tag: image-segmentation
 ---
 
 # FLAIR model collection
+
 The FLAIR models are a collection of semantic segmentation models initially developed to classify land cover on very high resolution aerial images (more specifically the French [BD ORTHO®](https://geoservices.ign.fr/bdortho) product). 
 The distributed pre-trained models differ in their :
 * dataset for training : [**FLAIR** dataset] (https://huggingface.co/datasets/IGNF/FLAIR) or the increased version of this dataset **FLAIR-INC** (x 3.5 patches). Only the FLAIR dataset is open at the moment.
@@ -98,10 +99,8 @@ The general characteristics of this specific model **FLAIR-INC_RVBIE_resnet34_un
 
 ## Model Informations
 
-<!-- Provide the basic links for the model. -->
-
-- **Repository:** https://github.com/IGNF/FLAIR-1-AI-Challenge
-- **Paper [optional]:** https://arxiv.org/pdf/2211.12979.pdf
+- **Code repository:** https://github.com/IGNF/FLAIR-1-AI-Challenge
+- **Paper:** https://arxiv.org/pdf/2211.12979.pdf
 - **Developed by:** IGN
 - **Compute infrastructure:** 
     - software: python, pytorch-lightning
@@ -110,18 +109,17 @@ The general characteristics of this specific model **FLAIR-INC_RVBIE_resnet34_un
 
   
 ## Uses
-<!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->
 
 Although the model can be applied to other type of very high spatial earth observation images, it was initially developed to tackle the problem of classifying aerial images acquired on the French Territory.
 The product called ([BD ORTHO®](https://geoservices.ign.fr/bdortho)) has its own spatial and radiometric specifications. The model is not intended to be generic to other type of very high spatial resolution images but specific to BD ORTHO images. 
-As a result, the prediction produced by the model would be all the better as the user images are similar to the original ones.
+Consequently, the model’s prediction would improve if the user images are similar to the original ones.
 
 _**Radiometry of input images**_ :
-The BD ORTHO input images are distributed in 8-bit encoding format per channel. When traning the model, input normalization was performed (see section **Traing Details**). 
+The BD ORTHO input images are distributed in 8-bit encoding format per channel. When traning the model, input normalization was performed (see section **Trainingg Details**). 
 It is recommended that the user apply the same type of input normalization while inferring the model.
 
 _**Multi-domain model**_ :
-The FLAIR-INC dataset that was used for training is composed of 75 radiometric domains. In the case of aerial images, domain shifts are frequent and are mainly due to : the date of acquisition of the aerial survey (april to november), the spatial domain (equivalent to a french department administrative division) and downstream radimetric processing.
+The FLAIR-INC dataset that was used for training is composed of 75 radiometric domains. In the case of aerial images, domain shifts are frequent and are mainly due to : the date of acquisition of the aerial survey (from april to november), the spatial domain (equivalent to a french department administrative division) and downstream radiometric processing.
 By construction (sampling 75 domains) the model is robust to these shifts, and can be applied to any images of the ([BD ORTHO® product](https://geoservices.ign.fr/bdortho)).
 
 _**Specification for the Elevation channel**_ :
@@ -130,18 +128,16 @@ When decoded to [0,255] ints, a difference of 1 should coresponds to 0.2 meters
 
 
 _**Land Cover classes of prediction**_ :
-The orginial class nomenclature of the FLAIR Dataset is made up of 19 classes (See the [FLAIR dataset](https://huggingface.co/datasets/IGNF/FLAIR) page for details).
-However 3 classes corresponding to uncertain labelisation (Mixed (16), Ligneous (17) and Other (19)) and 1 class with very poor labelling (Clear cut (15)) were deasctivated during training.
-As a result, the logits produced by the model are of size 19x1, but classes n° 15, 16, 17 and 19 should appear at 0 in the logits and should never predicted in the Argmax.
+The orginial class nomenclature of the FLAIR Dataset encompasses 19 classes (See the [FLAIR dataset](https://huggingface.co/datasets/IGNF/FLAIR) page for details).
+However 3 classes corresponding to uncertain labelisation (Mixed (16), Ligneous (17) and Other (19)) and 1 class with very poor labelling (Clear cut (15)) were desactivated during training.
+As a result, the logits produced by the model are of size 19x1, but classes n° 15, 16, 17 and 19 should appear at 0 in the logits and should not be present in the final argmax product.
 
 
-<!-- ## Bias, Risks, and Limitations -->
-## Bias, Risks, Limitations and Recommendations
 
-<!-- This section is meant to convey both technical and sociotechnical limitations. -->
+## Bias, Risks, Limitations and Recommendations
 
 _**Using the model on input images with other spatial resolution**_ :
-The FLAIR-INC_RVBIE_resnet34_unet_15cl_norm model was trained with fixed scale conditions. All patches used for training are derived from aerial images of 0.2 meters spatial resolution. Only flip and rotate augmentation were performed during the training process.  
+The FLAIR-INC_RVBIE_resnet34_unet_15cl_norm model was trained with fixed scale conditions. All patches used for training are derived from aerial images with 0.2 meters spatial resolution. Only flip and rotate augmentations were performed during the training process.  
 No data augmentation method concerning scale change was used during training. The user should pay attention that generalization issues can occur while applying this model to images that have different spatial resolutions.
 
 _**Using the model for other remote sensing sensors**_ :
@@ -153,11 +149,6 @@ The FLAIR-INC_RVBIE_resnet34_unet_15cl_norm model was trained on patches reprens
 The user should be aware that applying the model to other type of landscapes may imply a drop in model metrics.  
 
 
-<!--{{ bias_risks_limitations | default("[More Information Needed]", true)}}-->
-<!--### Recommendations-->
-<!-- This section is meant to convey recommendations with respect to the bias, risk, and technical limitations. -->
-<!--{{ bias_recommendations | default("Users (both direct and downstream) should be made aware of the risks, biases and limitations of the model. More information needed for further recommendations.", true)}}-->
-
 
 ## How to Get Started with the Model
 
@@ -171,26 +162,23 @@ Use the code below to get started with the model.
 
 ### Training Data
 
-<!-- This should link to a Dataset Card, perhaps with a short stub of information on what the training data is all about as well as documentation related to data pre-processing or additional filtering. -->
 218 400 patches of 512 x 512 pixels were used to train the **FLAIR-INC_RVBIE_resnet34_unet_15cl_norm** model. 
 The train/validation split was performed patchwise to obtain a 80% / 20% distribution between train and validation. 
 Annotation was performed at the _zone_ level (~100 patches per _zone_). Spatial independancy between patches is guaranted as patches from the same _zone_ were assigned to the same set (TRAIN or VALIDATION). 
-Here are the number of patches used for train and validation :
+The following number of patches were used for train and validation :
 | TRAIN set        | 174 700 patches    |
 | VALIDATION set       | 43 700 patchs      |
 
-<!--{{ training_data | default("[More Information Needed]", true)}} -->
 
 ### Training Procedure
 
-<!-- This relates heavily to the Technical Specifications. Content here should link to that section when it is relevant to the training procedure. -->
 
 #### Preprocessing [optional]
 
-For traning the model, input normalization was performed so as the input dataset has **a mean=0** and a **standard deviation = 1** channel wise. 
+For traning the model, input normalization was performed to center-reduce (**a mean=0** and a **standard deviation = 1**, channel wise) the dataset.
 We used the statistics of TRAIN+VALIDATION for input normalization. It is recommended that the user apply the same type of input normalization. 
 
-Here are the statistics of the TRAIN+VALIDATIOn set :
+Statistics of the TRAIN+VALIDATION set :
 
 | Modalities              | Mean (Train + Validation)       |Std    (Train + Validation)     |
 | ----------------------- | ----------- |----------- |
@@ -201,7 +189,7 @@ Here are the statistics of the TRAIN+VALIDATIOn set :
 | Elevation Channel (E)   | 53.26       |79.30       |
 
 
-<!--{{ preprocessing | default("[More Information Needed]", true)}} -->
+
 
 
 #### Training Hyperparameters
@@ -229,39 +217,37 @@ Here are the statistics of the TRAIN+VALIDATIOn set :
 
 #### Speeds, Sizes, Times [optional]
 
-<!-- This section provides information about throughput, start/end time, checkpoint size if relevant, etc. -->
 
 The FLAIR-INC_RVBIE_resnet34_unet_15cl_norm model was trained on a HPC/AI resources provided by GENCI-IDRIS (Grant 2022-A0131013803). 
-16 V100 GPUs were requested ( 4 nodes, 4 GPUS per node). With this configuration the approximate learning time is 6 minutes per epoch.
+16 V100 GPUs were used ( 4 nodes, 4 GPUS per node). With this configuration the approximate learning time is 6 minutes per epoch.
 
 FLAIR-INC_RVBIE_resnet34_unet_15cl_norm was obtained for num_epoch=76 with corresponding val_loss=0.56. 
 
-<!-- <img src="train_loss_FLAIR-INC_RGBIE_resnet34_unet_15cl_norm.png" alt="drawing" style="width:200px;"/>-->
-<!-- ![](train_loss_FLAIR-INC_RGBIE_resnet34_unet_15cl_norm.png)| ![](val_loss_FLAIR-INC_RGBIE_resnet34_unet_15cl_norm.png)-->
-
-| <div style="width:290px">TRAIN loss</div> |<div style="width:290px">VALIDATION loss</div>  |
-| --------------------------------------- | ------------------------------------- |
-| `<img src="train_loss_FLAIR-INC_RGBIE_resnet34_unet_15cl_norm.png" alt="drawing" style="width:300px;"/> |`<img src="val_loss_FLAIR-INC_RGBIE_resnet34_unet_15cl_norm.png" alt="drawing" style="width:300px;"/>  |
 
+<div style="display: flex; justify-content: space-between; width: 50%">
+  <div style="width: 45%;">
+    <p>TRAIN loss</p>
+    <img src="train_loss_FLAIR-INC_RGBIE_resnet34_unet_15cl_norm.png" alt="drawing" style="width: 100%;"/>
+  </div>
+  <div style="width: 45%;">
+    <p>VALIDATION loss</p>
+    <img src="val_loss_FLAIR-INC_RGBIE_resnet34_unet_15cl_norm.png" alt="drawing" style="width: 100%;"/>
+  </div>
+</div>
 
-<!-- {{ speeds_sizes_times | default("[More Information Needed]", true)}}-->
 
 ## Evaluation
 
-<!-- This section describes the evaluation protocols and provides the results. -->
-
 ### Testing Data, Factors & Metrics
 
 #### Testing Data
 
-<!-- This should link to a Dataset Card if possible. -->
 The evaluation was performed on a TEST set of 31 750 patches that are independant from the TRAIN and VALIDATION patches. They represent 15 spatio-temporal domains.
 The TEST set corresponds to the reunion of the TEST set of scientific challenges FLAIR#1 and FLAIR#2. See the [FLAIR challenge page](https://ignf.github.io/FLAIR/) for more details.
 
 The choice of a separate TEST set instead of cross validation was made to be coherent with the FLAIR challenges. 
 However the metrics for the Challenge were calculated on 12 classes and the TEST set acordingly. 
-As a result the _Snow_ class is unfortunately absent from the TEST set.
-<!-- {{ testing_data | default("[More Information Needed]", true)}} -->
+As a result the _Snow_ class is absent from the TEST set.
 
 #### Metrics
 
@@ -288,47 +274,41 @@ The following table give the class-wise metrics :
 | _snow_                    |  _00.00_    |  _00.00_  |  _00.00_  |  _00.00_  |
 | greenhouse              |  39.45    |  56.57  |  45.52  |  74.72  |
 | ----------------------- | ----------|---------|---------|---------|
-| **average**                 |  **58.63**    |  **72.44**  |  **74.3**  |  **72.49**  |
+| **average**             |  **58.63**    |  **72.44**  |  **74.3**  |  **72.49**  |
 
-<!-- These are the evaluation metrics being used, ideally with a description of why. -->
 
-{{ testing_metrics | default("[More Information Needed]", true)}}
 
-The following illustration give the confusion matrix :
+The following illustration gives the resulting confusion matrix :
 * Left : normalised acording to columns, columns sum at 100% and the **precision** is on the diagonal of the matrix
 * Right : normalised acording to rows, rows sum at 100% and the **recall** is on the diagonal of the matrix 
 
 
-| <div style="width:290px">Normalised confusion Matrix (precision)</div> |<div style="width:290px">Normalised Confusion Matrix (recall)</div>  |
-| --------------------------------------- | ------------------------------------- |
-| `<img src="FLAIR-INC_RVBIE_resnet34_unet_15cl_norm_cm-precision.png" alt="drawing" style="width:300px;"/> |`<img src="FLAIR-INC_RVBIE_resnet34_unet_15cl_norm_cm-recall.png" alt="drawing" style="width:300px;"/>  |
-
-
-### Results
+<div style="display: flex; justify-content: space-between;">
+  <div style="width: 45%;">
+    <p>Normalised confusion Matrix (precision)</p>
+    <img src="FLAIR-INC_RVBIE_resnet34_unet_15cl_norm_cm-precision.png" alt="drawing" style="width: 100%;"/>
+  </div>
+  <div style="width: 45%;">
+    <p>Normalised Confusion Matrix (recall)</p>
+    <img src="FLAIR-INC_RVBIE_resnet34_unet_15cl_norm_cm-recall.png" alt="drawing" style="width: 100%;"/>
+  </div>
+</div>
 
-<!-- Gio : Add inferenvce Sample ??? -->
 
-{{ results | default("[More Information Needed]", true)}}
 
-#### Summary
 
-{{ results_summary | default("", true) }}
 
+### Results
 
-## Technical Specifications [optional]
-
-### Model Architecture and Objective
-
-{{ model_specs | default("[More Information Needed]", true)}}
+Samples of results
 
 
 ## Citation [optional]
 
-<!-- If there is a paper or blog post introducing the model, the APA and Bibtex information for that should go in this section. -->
 
 **BibTeX:**
 
-@misc{garioud2023flair,
+@inproceeding{garioud2023flair,
       title={FLAIR: a Country-Scale Land Cover Semantic Segmentation Dataset From Multi-Source Optical Imagery}, 
       author={Anatol Garioud and Nicolas Gonthier and Loic Landrieu and Apolline De Wit and Marion Valette and Marc Poupée and Sébastien Giordano and Boris Wattrelos},
       year={2023},
@@ -337,7 +317,6 @@ The following illustration give the confusion matrix :
       primaryClass={cs.CV}
 }
 
-{{ citation_bibtex | default("[More Information Needed]", true)}}
 
 **APA:**
 Garioud, A., Gonthier, N., Landrieu, L., De Wit, A., Valette, M., Poupée, M., ... & Wattrelos, B. (2023). FLAIR: a Country-Scale Land Cover Semantic Segmentation Dataset From Multi-Source Optical Imagery. arXiv preprint arXiv:2310.13336.