remote-sensing/REPORT_ENHANCEMENT_GUIDE.md

# 📊 Báo Cáo HTML - PSNR Baseline & Hyperparameters Chi Tiết

## ✅ Cập Nhật Hoàn Thành

Hệ thống báo cáo HTML đã được nâng cấp để bao gồm:

1. **PSNR Baseline Metrics** - Đánh giá chất lượng model cloud removal
2. **Hyperparameters Chi Tiết** - Tất cả thông số để tái hiện training
3. **Auto-Generate Report** - Tự động tạo báo cáo sau khi training xong

---

## 🎯 Tính Năng Mới

### 1. PSNR Baseline Analysis

Báo cáo giờ hiển thị 3 metrics cards cho cloud removal:

```
┌─────────────────┬─────────────────┬─────────────────┐
│ 📈 Model PSNR   │ 📉 Baseline PSNR│ ⚡ Improvement  │
│   25.43 dB      │   18.50 dB      │   +6.93 dB      │
└─────────────────┴─────────────────┴─────────────────┘
```

**Phân tích PSNR Baseline:**
- ✅ **Model > Baseline**: Màu xanh - Model TỐT HƠN không làm gì
- ❌ **Model < Baseline**: Màu cam - Model TỆ HƠN không làm gì

**Giải thích:**
- **Baseline PSNR**: PSNR giữa ảnh cloudy và ảnh clean (không xử lý)
- **Model PSNR**: PSNR giữa output model và ảnh clean
- **Improvement**: Model PSNR - Baseline PSNR
- **% Improvement**: (Improvement / Baseline) × 100%

### 2. Hyperparameters Chi Tiết

Section mới "🎯 Hyperparameters - Chi Tiết Tái Hiện" bao gồm:

#### Model Hyperparameters
```python
model_type: unet
n_estimators: 200       # (cho Random Forest)
max_depth: 30
learning_rate: 0.0001
batch_size: 8
num_epochs: 50
use_gpu: True
use_s1: True           # Sentinel-1 radar data
```

#### Data Processing
```python
test_size: 0.2
feature_mode: image    # hoặc 'simple', 'extended'
n_features: 6
features: ['B02', 'B03', 'B04', 'B08', 'VV', 'VH']
```

#### Geo & Time Parameters
```python
bbox: [105.5, 9.2, 106.4, 10.0]
time_range: "2023-03-01/2023-12-31"
resolution: 10m
```

### 3. Training Reproducibility

Box đặc biệt với hướng dẫn:

```
📝 Lưu ý:
• Lưu toàn bộ các tham số trên để reproduce kết quả
• Sử dụng cùng dataset và time range để đảm bảo tính nhất quán
• Random seed: 42 (mặc định)
• Generated: 23/02/2026 14:35:42
```

---

## 📁 Files Đã Cập Nhật

### 1. [report_generator.py](report_generator.py)

**Function: `generate_training_report()`**

Thêm mới:
- Extract `val_psnr`, `baseline_psnr`, `improvement`
- Extract `hyperparameters` dict từ training_result
- Parse common hyperparameters (n_estimators, max_depth, learning_rate, etc.)
- Extract features, feature_mode, data_source

**HTML Template Updates:**
- Thêm 3 stat cards cho PSNR metrics
- Section "PSNR Baseline Analysis" với màu sắc động
- Section "Hyperparameters - Chi Tiết Tái Hiện"
  - Model Hyperparameters
  - Data Processing
  - Geo & Time Parameters
- Box hướng dẫn reproducibility

### 2. [train_cloud_removal.py](train_cloud_removal.py)

**Function: `train_cloud_removal_model()`**

Thêm vào `torch.save()`:
```python
'hyperparameters': {
    'data_dir': data_dir,
    'use_s1': use_s1,
    'batch_size': batch_size,
    'num_epochs': num_epochs,
    'learning_rate': learning_rate,
    'device': device,
    'model_type': 'unet',
    'architecture': 'U-Net',
    'optimizer': 'Adam',
    'criterion': 'L1Loss',
    'scheduler': 'ReduceLROnPlateau',
    'train_size': len(train_dataset),
    'val_size': len(val_dataset),
    'test_size': 0.2,
    's2_bands': len(s2_bands),
    'feature_mode': 'image',
    'random_seed': 42
}
```

### 3. [api_server.py](api_server.py)

**Function: `list_cloud_removal_models()`**

Thêm extract từ checkpoint:
```python
val_psnr = checkpoint.get('val_psnr', None)
baseline_psnr = checkpoint.get('baseline_psnr', None)
hyperparams = checkpoint.get('hyperparameters', {})
```

**Function: `run_cloud_training()`**

Thêm auto-generate report sau khi training:
```python
training_result = {
    'val_psnr': val_psnrs[-1],
    'baseline_psnr': baseline_psnr,
    'hyperparameters': {...},
    'data_source': ...,
    'collections': [...],
    'features': [...]
}

report_path, _ = generate_training_report(training_result)
```

---

## 🚀 Cách Sử Dụng

### 1. Training Cloud Removal

```bash
# Start API server
python api_server.py

# Hoặc qua web interface
http://localhost:8000/cloud-training
```

Sau khi training xong:
1. ✅ Model được lưu với đầy đủ metadata + hyperparameters
2. ✅ Báo cáo HTML tự động được tạo trong `reports/`
3. ✅ Báo cáo bao gồm PSNR baseline + hyperparameters

### 2. Xem Báo Cáo

```bash
# Qua web interface
http://localhost:8000/reports

# Hoặc mở trực tiếp file
reports/training_report_YYYYMMDD_HHMMSS.html
```

### 3. Tái Hiện Training

Mở báo cáo HTML → Xem section "Hyperparameters" → Copy tất cả tham số:

```python
# Reproduction example
from train_cloud_removal import train_cloud_removal_model

model, train_losses, val_losses, val_psnrs, baseline_psnr = train_cloud_removal_model(
    data_dir="winter_dataset",
    use_s1=True,
    batch_size=8,
    num_epochs=50,
    learning_rate=1e-4,
    device="cuda",
    save_dir="cloud_removal_model"
)
```

---

## 📊 Ví Dụ Báo Cáo

### Cloud Removal Training Report

```html
📊 Báo Cáo Training Model
Land Classification - 23/02/2026 14:35:42

📈 Tóm Tắt Kết Quả
┌──────────────┬──────────────┬──────────────┐
│ Model PSNR   │ Baseline PSNR│ Improvement  │
│  25.43 dB    │  18.50 dB    │  +6.93 dB    │
└──────────────┴──────────────┴──────────────┘

🎯 PSNR Baseline Analysis
✅ Model TỐT HƠN baseline - Kết quả đáng tin cậy!

Model PSNR:      25.43 dB
Baseline PSNR:   18.50 dB (cận dưới)
Improvement:     +6.93 dB (+37.5%)

Giải thích:
- Baseline PSNR: PSNR giữa ảnh cloudy và ảnh clean (không làm gì)
- Model PSNR: PSNR giữa output model và ảnh clean
- Improvement > 0: Model đang khử mây hiệu quả!

⚙️ Cấu Hình Training
Model Type:      UNET
Data Source:     SEN12MS-CR Dataset (winter_dataset)
Collections:     Sentinel-2 L2A, Sentinel-1 RTC
Model Path:      cloud_removal_model/cloud_removal_unet_best.pth

🎯 Hyperparameters - Chi Tiết Tái Hiện

📊 Model Hyperparameters
model_type:      unet
learning_rate:   0.0001
batch_size:      8
num_epochs:      50
use_gpu:         True
use_s1:          True

📦 Data Processing
test_size:       0.2
feature_mode:    image
n_features:      6
features:        B02, B03, B04, B08, VV, VH

🌍 Geo & Time Parameters
bbox:            []
time_range:      
resolution:      10m

📝 Lưu ý:
• Lưu toàn bộ các tham số trên để reproduce kết quả
• Sử dụng cùng dataset và time range để đảm bảo tính nhất quán
• Random seed: 42 (mặc định)
```

---

## 🔍 So Sánh Trước & Sau

### ❌ Trước (Thiếu thông tin)

```
📊 Tóm Tắt Kết Quả
- Train Loss: 0.0123
- Val Loss: 0.0098

⚙️ Cấu Hình
- Model: U-Net
- Batch Size: 8
```

**Vấn đề:**
- ❌ Không có PSNR baseline → Không biết model có tốt không
- ❌ Thiếu hyperparameters → Không tái hiện được
- ❌ Thiếu data info → Không biết dataset gì

### ✅ Sau (Đầy đủ)

```
📊 Tóm Tắt Kết Quả
- Model PSNR: 25.43 dB
- Baseline PSNR: 18.50 dB
- Improvement: +6.93 dB (+37.5%)
- Train Loss: 0.0123
- Val Loss: 0.0098

🎯 PSNR Baseline Analysis
✅ Model TỐT HƠN baseline - Kết quả đáng tin cậy!

🎯 Hyperparameters (Đầy đủ để reproduce)
- Model: U-Net
- Learning Rate: 0.0001
- Batch Size: 8
- Epochs: 50
- Use S1: True
- Test Size: 0.2
- Feature Mode: image
- Random Seed: 42
- Dataset: SEN12MS-CR (winter_dataset)
- Collections: Sentinel-2 L2A, Sentinel-1 RTC
```

**Lợi ích:**
- ✅ Có PSNR baseline → Đánh giá chính xác chất lượng
- ✅ Có đầy đủ hyperparameters → Tái hiện dễ dàng
- ✅ Có data info → Biết nguồn gốc dataset

---

## 💡 Best Practices

### 1. Luôn Lưu Báo Cáo

Sau mỗi lần training:
```bash
# Báo cáo tự động được tạo tại
reports/training_report_20260223_143542.html
```

### 2. Đặt Tên Model Rõ Ràng

```
cloud_removal_unet_best.pth
├─ Epoch: 48
├─ PSNR: 25.43 dB
├─ Baseline: 18.50 dB
└─ Hyperparameters: {...}
```

### 3. Version Control Hyperparameters

Khi thử nghiệm:
```python
# Experiment 1
learning_rate = 1e-4
batch_size = 8
# → PSNR = 25.43 dB

# Experiment 2
learning_rate = 1e-3
batch_size = 16
# → PSNR = 26.12 dB ✅ Better!
```

Báo cáo sẽ tự động ghi lại để so sánh.

### 4. Share Kết Quả

```bash
# Share HTML report
cp reports/training_report_20260223_143542.html /shared/results/

# Người khác có thể:
1. Xem kết quả chi tiết
2. Lấy hyperparameters để reproduce
3. Hiểu được baseline performance
```

---

## 📚 Technical Details

### PSNR Calculation

```python
def calculate_psnr(img1, img2, max_value=1.0):
    mse = torch.mean((img1 - img2) ** 2)
    if mse == 0:
        return float('inf')
    psnr = 20 * math.log10(max_value) - 10 * torch.log10(mse)
    return psnr.item()
```

### Baseline PSNR

```python
def calculate_baseline_psnr(dataloader, device):
    # PSNR between cloudy input and clean target
    # This is the "do nothing" baseline
    total_psnr = 0
    for inputs, targets in dataloader:
        s2_cloudy = inputs[:, :num_s2_bands, :, :]
        psnr = calculate_psnr(s2_cloudy, targets)
        total_psnr += psnr
    return total_psnr / len(dataloader)
```

### Report Generation

```python
# In api_server.py - run_cloud_training()
training_result = {
    'val_psnr': val_psnrs[-1],
    'baseline_psnr': baseline_psnr,
    'hyperparameters': {
        'data_dir': config.data_dir,
        'use_s1': config.use_s1,
        'batch_size': config.batch_size,
        'num_epochs': config.num_epochs,
        'learning_rate': config.learning_rate,
        # ... more
    },
    # ... more fields
}

report_path, _ = generate_training_report(training_result)
```

---

## 🎓 Hiểu Về PSNR Baseline

### Tại Sao Cần Baseline?

**Scenario 1: Baseline = 18.5 dB, Model = 25.4 dB**
- Improvement = +6.9 dB (+37%)
- ✅ Model TỐT! Đáng để deploy

**Scenario 2: Baseline = 18.5 dB, Model = 16.2 dB**
- Improvement = -2.3 dB (-12%)
- ❌ Model TỆ! Làm TỒI hơn không làm gì!

**Scenario 3: Baseline = 25.0 dB, Model = 25.5 dB**
- Improvement = +0.5 dB (+2%)
- ⚠️ Model OK nhưng cải thiện ít, có thể không đáng effort

### PSNR Thresholds

| PSNR (dB) | Quality | Note |
|-----------|---------|------|
| < 20 | Poor | Nhiều artifacts |
| 20-25 | Fair | Chấp nhận được |
| 25-30 | Good | Chất lượng tốt |
| 30-35 | Very Good | Rất tốt |
| > 35 | Excellent | Xuất sắc |

### Improvement Thresholds

| Improvement | Đánh Giá | Quyết Định |
|-------------|----------|-----------|
| < 0 dB | Tệ | Không dùng model |
| 0-2 dB | Yếu | Cần cải thiện |
| 2-5 dB | OK | Chấp nhận được |
| 5-10 dB | Tốt | Đáng deploy |
| > 10 dB | Xuất sắc | Deploy ngay! |

---

## 🔧 Troubleshooting

### Lỗi: Báo cáo không có PSNR

**Nguyên nhân:** Model cũ chưa lưu `val_psnr` và `baseline_psnr`

**Giải pháp:** Train lại model với code mới:
```bash
python train_cloud_removal.py
```

### Lỗi: Hyperparameters bị thiếu

**Nguyên nhân:** Training result không có `hyperparameters` dict

**Giải pháp:** Đảm bảo `torch.save()` bao gồm:
```python
torch.save({
    ...,
    'hyperparameters': {...}
}, path)
```

### Báo cáo không tự động tạo

**Kiểm tra:**
```python
# In api_server.py - run_cloud_training()
try:
    report_path, _ = generate_training_report(training_result)
    print(f"[REPORT] Generated: {report_path}")
except Exception as e:
    print(f"[REPORT ERROR] {e}")
```

---

## ✨ Summary

### Đã Thêm:
1. ✅ **PSNR Baseline** metrics trong báo cáo
2. ✅ **Chi tiết Hyperparameters** để reproduce
3. ✅ **Auto-generate report** sau training
4. ✅ **Visual indicators** (màu sắc) cho PSNR
5. ✅ **Hướng dẫn reproducibility**

### Files Cập Nhật:
- ✅ [report_generator.py](report_generator.py)
- ✅ [train_cloud_removal.py](train_cloud_removal.py)
- ✅ [api_server.py](api_server.py)

### Lợi Ích:
- 📊 **Đánh giá chính xác** chất lượng model
- 🔄 **Tái hiện dễ dàng** kết quả training
- 📝 **Tài liệu đầy đủ** cho mỗi experiment
- 🎯 **So sánh khoa học** giữa các model
- ✅ **Professional workflow** cho research

**Giờ bạn có hệ thống báo cáo cực kỳ chuyên nghiệp! 🚀**