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

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

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

Geo & Time Parameters

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

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

Function: train_cloud_removal_model()

Thêm vào torch.save():

'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

Function: list_cloud_removal_models()

Thêm extract từ checkpoint:

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:

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

# 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

# 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ố:

# 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

📊 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:

# 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:

# 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ả

# 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

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

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

# 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:

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:

torch.save({
    ...,
    'hyperparameters': {...}
}, path)

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

Kiểm tra:

# 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
• ✅ train_cloud_removal.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! 🚀