From 18c6a1c94914ff66771e6c7d014dfe118017f34d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gr=C3=A9goire=20Mureau?= Date: Thu, 10 Sep 2026 01:50:07 +0200 Subject: [PATCH] docs: README bilingue FR/EN (racine + app/) Co-authored-by: Cursor --- README.MD => README.fr.md | 2 + README.md | 131 ++++++++++++++++++++++++++++++++ app/{README.MD => README.fr.md} | 2 + app/README.md | 110 +++++++++++++++++++++++++++ 4 files changed, 245 insertions(+) rename README.MD => README.fr.md (98%) create mode 100644 README.md rename app/{README.MD => README.fr.md} (96%) create mode 100644 app/README.md diff --git a/README.MD b/README.fr.md similarity index 98% rename from README.MD rename to README.fr.md index cddde2d..a2ef73c 100644 --- a/README.MD +++ b/README.fr.md @@ -1,5 +1,7 @@ # Street Vision PoC - Segmentation Sémantique Urbaine +📘 Ce projet est également disponible en [anglais 🇬🇧](./README.md) + **Source de vérité** : [Forgejo](https://git.gregoiremureau.com/openclassroom-ai/oc-p09-street-vision-poc) (auto-hébergé). ```bash diff --git a/README.md b/README.md new file mode 100644 index 0000000..6b3a0d4 --- /dev/null +++ b/README.md @@ -0,0 +1,131 @@ +# Street Vision PoC - Urban Semantic Segmentation + +📘 This project is also available in [French 🇫🇷](./README.fr.md) + +**Source of truth** : [Forgejo](https://git.gregoiremureau.com/openclassroom-ai/oc-p09-street-vision-poc) (self-hosted). + +```bash +git clone https://git.gregoiremureau.com/openclassroom-ai/oc-p09-street-vision-poc.git +git clone https://git.gregoiremureau.com/openclassroom-ai/oc-p09-street-vision-poc.git +``` + +Prod: https://api.gregoiremureau.com/ml/street-vision-poc/ + +Dataset: `./fetch-data.sh` (Cityscapes **not** in git). + +## 🎯 Project Description + +**Street Vision PoC** is a proof of concept demonstrating the improvement of urban semantic segmentation performance by comparing traditional CNN architectures (FPN) with modern Transformer approaches (SegFormer). + +This project empirically evaluates the potential of **Vision Transformers** for understanding complex urban scenes, with a focus on safety-critical classes (pedestrians, vehicles, signage). + +### 🔬 Technical Context + +- **Dataset**: Cityscapes (2,975 high-resolution pixel-by-pixel annotated images) +- **Compared architectures**: + - **Traditional CNN**: FPN + EfficientNet-B0/ResNet34 + - **Vision Transformer**: SegFormer-B0/B1 +- **Evaluation resolutions**: 512×512 and 768×768 pixels +- **Main metric**: Mean Intersection over Union (mIoU) + +## 📊 Main Results + +| **Model** | **mIoU** | **Parameters** | **Size** | **Performance** | +|------------|----------|----------------|------------|-----------------| +| **SegFormer-B1** | **79.98%** | 13.68M | 52MB | ⭐ **Best** | +| **FPN+ResNet34** | 79.22% | 23.16M | 88MB | 🔄 Strong baseline | +| **FPN+EfficientNet-B0** | 78.67% | 5.76M | 22MB | 💡 Compact | +| **SegFormer-B0** | 77.91% | 3.72M | 14MB | ⚡ Ultra-lightweight | + +**Comparative analysis**: SegFormer-B1 and FPN+ResNet34 achieve similar performance (~79-80% mIoU), but SegFormer-B1 has the advantage of being more compact and likely faster on GPU. The SegFormer-B2 to B5 versions would promise significant gains, but my hardware constraints did not allow their evaluation. + +### 🎯 Significant Gains by Critical Classes + +- **Human**: +1.78% IoU (safety-critical) +- **Vehicle**: +1.05% IoU (mobile obstacles) +- **Object**: +0.56% IoU (urban signage) + +## 🚀 Quick Deployment + +### Docker Hub + +The application is containerized and available on Docker Hub: + +```bash +docker pull grgmdmn/street-vision-poc_api +# live prod: +# https://api.gregoiremureau.com/ml/street-vision-poc/ +``` + +### Configuration with Docker Compose + +1. Copy the example configuration file: +```bash +cp docker-compose.yml.example docker-compose.yml +``` + +2. Configure the environment variables in `docker-compose.yml`. + +3. Launch the application: +```bash +docker-compose up -d +``` + +4. Access the interface: `http://localhost:$(port)` + +## 🎮 Interface Features + +### Interactive Dashboard + +- **Image upload**: Drag-and-drop of urban images +- **Dual inference**: Simultaneous comparison of FPN vs SegFormer +- **Visualization**: Segmentation masks colored by class +- **Real-time metrics**: Inference time and confidence scores +- **Export**: Download of segmentation results +- **WCAG accessibility**: Interface compliant with accessibility standards + +### Exploratory Data Analysis + +- **Cityscapes statistics**: Class distribution, native resolutions +- **Interactive charts**: Pixel breakdown by meta-class +- **Annotated examples**: Visualization of dataset samples + +## 📈 Evaluation Methodology + +### Comparative Approach + +1. **CNN baseline**: FPN+EfficientNet/ResNet retraining at higher resolutions +2. **New approach**: SegFormer evaluation with global attention +3. **Rigorous protocol**: Cross-validation, standardized metrics +4. **Per-class analysis**: Detailed performance across 8 urban meta-classes + +### Identified Limitations + +- **Fixed resolution**: Evaluation without sliding window (vs. original protocol) +- **Limited resources**: Tests only on SegFormer-B0/B1 +- **Controlled conditions**: Cityscapes dataset only (favorable weather) + +## 🔬 Technical Insights + +### SegFormer Advantages + +- **Global attention**: Every pixel "sees" the entire image simultaneously +- **Lighter architecture**: Compact model with fewer parameters +- **Contextual robustness**: Better handling of occlusions and complex objects +- **Improvement potential**: B2-B5 versions would promise significant gains + +### Identified Trade-offs + +- **Classic CPU speed**: ~2x slower than FPN on high-performance processors (Xeon, 9600X) +- **Energy-efficient CPU speed**: 3x faster on energy-efficient processors (N100) +- **GPU optimization**: Transformer architecture favored by hardware acceleration + +## 📚 References + +- **Xie, E. et al.** (2021). *SegFormer: Simple and Efficient Design for Semantic Segmentation with Transformers*. NeurIPS 2021. +- **Cordts, M. et al.** (2016). *The Cityscapes Dataset for Semantic Urban Scene Understanding*. CVPR 2016. +- **Segmentation Models PyTorch** - [Implementation framework used](https://github.com/qubvel/segmentation_models.pytorch) + +--- + +**Note**: This proof of concept demonstrates the potential of Transformer architectures for urban segmentation, while highlighting the importance of computational resources to fully leverage their capabilities. diff --git a/app/README.MD b/app/README.fr.md similarity index 96% rename from app/README.MD rename to app/README.fr.md index 7b27e38..86da936 100644 --- a/app/README.MD +++ b/app/README.fr.md @@ -1,6 +1,8 @@ # Dashboard de Comparaison de Modèles +📘 Cette documentation est aussi disponible en [anglais 🇬🇧](./README.md) + ## Conformité aux Exigences ### Analyse Exploratoire des Données Non Structurées (Images) diff --git a/app/README.md b/app/README.md new file mode 100644 index 0000000..1d0396b --- /dev/null +++ b/app/README.md @@ -0,0 +1,110 @@ + +# Model Comparison Dashboard + +📘 This documentation is also available in [French 🇫🇷](./README.fr.md) + +## Compliance with Requirements + +### Exploratory Analysis of Unstructured Data (Images) + +**Display of image examples by category:** +- Visualization of Cityscapes dataset images organized by 8 segmentation meta-classes +- Interactive selection of training and test images with preview +- Category navigation interface with user-friendly display names + +**Data counting and distribution:** +- Pie charts detailing the distribution of the 25,000 Cityscapes images +- Visualization of project usage: 80% train / 20% validation / 100% test +- Class distribution chart for the training dataset +- Summary tables with detailed statistics per split + +**Image transformations:** +- Interactive demonstration of preprocessing: resizing and normalization +- Visualization of random data augmentations (rotation, flip, brightness, etc.) +- Before/after comparison of transformations with visual alignment +- Complete documentation of the 6 possible augmentation types + +### Input Data Selection + +**Multiple selection interface:** +- Dropdown list for Cityscapes test images with ground truth information +- Upload of personal files (JPEG, PNG) with format validation +- Preview of selected images before processing +- Error handling and real-time user feedback + +### Prediction Results + +**Full model comparison:** +- Side-by-side display of predictions from the two best models +- Visualizations with original image, predicted masks, and ground truth +- Detection and highlighting of segmentation errors +- Detailed per-class statistics with percentages and pixel counts + +**Performance metrics:** +- Comparative inference time with speed analysis +- Performance scores (mIoU, Accuracy) per model +- Per-class IoU for detailed performance analysis +- Interactive comparative result charts + +### Cloud Deployment + +**Deployed architecture:** +- FastAPI application for the model comparison API +- Streamlit interface for the user dashboard +- Deployment on cloud infrastructure with high availability +- Automatic resource management and scaling + +### WCAG Accessibility + +**Compliance with essential criteria:** + +#### Color Contrast (WCAG AA) +- Color palette with contrast ratios ≥ 4.1:1 for graphical elements +- Contrast ratios ≥ 4.5:1 for text on background +- 8 main colors validated: blue (#0066CC), red (#CC0000), green (#006600), etc. +- Replacement of gradients with solid, high-contrast colors + +#### Text Alternatives +- Detailed alternative descriptions for all automatically generated charts +- Explanatory text for each visualization (pie charts, bar charts) +- Appropriate ARIA labels for interactive elements +- Complete textual documentation of image transformations + +#### Non-Color-Only Indication +- Patterns and hatching complementary to colors (optional via checkbox) +- 6 different patterns: diagonal, vertical, horizontal, dots, cross +- Differentiation by shape and texture in addition to colors +- Reinforced borders and outlines for visual distinction + +#### Keyboard Navigation +- Visible CSS focus with 2px blue outlines (#0066CC) +- Full support for tab navigation +- Clear visual indicators for focused elements +- Compliance with logical navigation order + +#### Accessible Data Tables +- Structured tables complementary to all charts +- Appropriate headers with scope and descriptions +- Exportable data readable by screen readers +- Responsive configuration for all screens + +**Built-in assistive features:** +- "Enable patterns (visual accessibility)" checkbox for customization +- Automatic chart descriptions with complete statistics +- Interface adaptable to the needs of users with disabilities +- Complete documentation of accessibility features via the `/accessibility-info` endpoint + +## Technical Architecture + +**Technology stack:** +- Backend: FastAPI + PyTorch for model inference +- Frontend: Streamlit with accessible components +- Visualizations: Matplotlib with WCAG palettes +- REST API documented with Pydantic validation +- Optimized state management for model comparisons + +**Performance and reliability:** +- Optimized inference times (< 1 second per image) +- Efficient memory management with automatic figure closing +- File format and size validation +- Automatic cleanup of temporary files