docs: README bilingue FR/EN (racine + app/)
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
parent
599aa3a67d
commit
18c6a1c949
4 changed files with 245 additions and 0 deletions
|
|
@ -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
|
||||
131
README.md
Normal file
131
README.md
Normal file
|
|
@ -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.
|
||||
|
|
@ -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)
|
||||
110
app/README.md
Normal file
110
app/README.md
Normal file
|
|
@ -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
|
||||
Loading…
Add table
Reference in a new issue