remote-sensing/CLOUD_PROCESSING.md

# Xử lý mây (Cloud Processing) — Hệ thống Land Classification

Tài liệu chi tiết về các phương pháp xử lý mây cho dữ liệu Sentinel-2. Module độc lập `cloud_removal.py` cung cấp nhiều chiến lược có thể chọn.

## Tổng quan

Hệ thống cung cấp **7 phương pháp xử lý mây** khác nhau, từ cổ điển đến hiện đại (ML/DL):

1. **Classic** - 3 bước cổ điển (temporal → median → spatial) - mặc định
2. **Temporal Only** - Chỉ temporal interpolation (nhanh nhất)
3. **Median Composite** - Ưu tiên median composite (giảm nhiễu tốt nhất)
4. **ML KNN** - Machine Learning K-Nearest Neighbors inpainting
5. **ML RF** - Machine Learning Random Forest inpainting
6. **Deep Inpainting** - Deep Learning CNN inpainting (yêu cầu model)
7. **Hybrid** - Kết hợp classical + ML (cân bằng tốc độ và chất lượng)

---

## Cách sử dụng

### API Endpoint

Lấy danh sách các methods:
```bash
GET /api/cloud-removal/methods
```

Response:
```json
{
  "success": true,
  "methods": {
    "classic": "3-step classical: temporal → median → spatial (default, balanced)",
    "temporal_only": "Temporal interpolation only (fastest, needs many scenes)",
    "median_composite": "Median composite priority (best noise reduction)",
    "ml_knn": "ML K-Nearest Neighbors inpainting (good quality, medium speed)",
    "ml_rf": "ML Random Forest inpainting (high quality, slower)",
    "deep": "Deep Learning CNN inpainting (best quality, requires model)",
    "hybrid": "Hybrid classical + ML (balanced speed & quality)"
  },
  "default": "classic"
}
```

### Config trong Prediction

Thêm `cloud_removal_method` vào config:

```python
config = {
    "model_filename": "model_odc.joblib",
    "min_lon": 105.5,
    "max_lon": 105.6,
    "min_lat": 10.0,
    "max_lat": 10.1,
    "start_date": "2024-01-01",
    "end_date": "2024-12-31",
    "max_scenes": 12,
    "cloud_cover": 30,
    "resolution": 20,
    "use_gpu": false,
    "cloud_removal_method": "hybrid"  # Chọn method tại đây
}
```

### Programmatic Usage

```python
from cloud_removal import process_cloud_removal

# Load Sentinel-2 data with SCL band
s2_data = load(...) 

# Process clouds with selected method
cleaned_data, metadata = process_cloud_removal(
    s2_data=s2_data,
    method="hybrid",  # or "classic", "ml_knn", etc.
    verbose=True
)

print(f"Cloud coverage: {metadata['cloud_coverage_percent']:.1f}%")
print(f"Steps applied: {metadata['steps_applied']}")
```

---

## Chi tiết các phương pháp

### 1. Classic (Mặc định)

**Mô tả:** 3 bước cổ điển kết hợp temporal, median, và spatial interpolation.

**Quy trình:**
1. Temporal interpolation (ffill + bfill)
2. Median compositing (nếu >= 3 scenes)
3. Spatial interpolation (nearest neighbor)
4. Fallback fillna(0)

**Ưu điểm:**
- Cân bằng tốc độ và chất lượng
- Đã được test kỹ, ổn định
- Phù hợp hầu hết trường hợp

**Nhược điểm:**
- Không tối ưu cho các gaps lớn
- Có thể tạo artifacts ở biên

**Khi nào dùng:** Default choice, phù hợp cho production

---

### 2. Temporal Only

**Mô tả:** Chỉ sử dụng temporal interpolation (ffill + bfill).

**Ưu điểm:**
- Nhanh nhất
- Giữ xu hướng thời gian tốt
- Ít tạo artifacts

**Nhược điểm:**
- Yêu cầu nhiều time steps
- Không xử lý được gaps liên tục
- Chất lượng kém nếu ít scenes

**Khi nào dùng:** Khi có nhiều scenes (>10) và cần tốc độ

---

### 3. Median Composite

**Mô tả:** Ưu tiên median composite, sau đó spatial interpolation.

**Ưu điểm:**
- Giảm nhiễu tốt nhất
- Chống outliers hiệu quả
- Tạo composite trơn

**Nhược điểm:**
- Mất thông tin temporal
- Yêu cầu >= 3 scenes
- Chậm hơn temporal only

**Khi nào dùng:** Khi cần giảm nhiễu, không quan tâm temporal dynamics

---

### 4. ML KNN Inpainting

**Mô tả:** Sử dụng K-Nearest Neighbors để học từ pixels hợp lệ và dự đoán pixels bị mây.

**Quy trình:**
1. Xác định valid pixels (không có mây)
2. Train KNN model với spatial coordinates + spectral values
3. Predict invalid pixels
4. Fill predictions vào dataset

**Ưu điểm:**
- Chất lượng cao hơn classical
- Học spatial patterns
- Không cần pretrained model

**Nhược điểm:**
- Chậm hơn classical
- Yêu cầu đủ valid pixels (>10)
- Tốn RAM nếu ảnh lớn

**Hyperparameters:**
- n_neighbors: 5
- weights: 'distance'

**Khi nào dùng:** Khi cần chất lượng cao và có đủ valid pixels

---

### 5. ML Random Forest Inpainting

**Mô tả:** Sử dụng Random Forest để inpainting, tương tự KNN nhưng phức tạp hơn.

**Ưu điểm:**
- Chất lượng cao nhất trong ML methods
- Xử lý non-linear patterns tốt
- Robust với outliers

**Nhược điểm:**
- Chậm nhất trong ML methods
- Tốn nhiều RAM
- Có thể overfit với ít data

**Hyperparameters:**
- n_estimators: 10
- max_depth: 10
- n_jobs: -1 (parallel)

**Khi nào dùng:** Khi cần chất lượng tối đa và không quan tâm tốc độ

---

### 6. Deep Inpainting (CNN)

**Mô tả:** Sử dụng CNN autoencoder để reconstruct pixels bị mây.

**Trạng thái:** **Đang phát triển** - yêu cầu pretrained model

**Quy trình (planned):**
1. Stack bands thành multi-channel image
2. Tạo binary mask (1=cloud, 0=valid)
3. Run through CNN autoencoder
4. Blend predictions với valid pixels

**Ưu điểm (khi có model):**
- Chất lượng tốt nhất
- Xử lý large gaps hiệu quả
- Học global context

**Nhược điểm:**
- Yêu cầu pretrained model
- Chậm nhất (GPU recommended)
- Phức tạp để deploy

**Khi nào dùng:** Khi có GPU và pretrained model, cần chất lượng tối đa

---

### 7. Hybrid (Khuyến nghị)

**Mô tả:** Kết hợp classical + ML để cân bằng tốc độ và chất lượng.

**Quy trình:**
1. Temporal interpolation (nhanh)
2. Check remaining NaN percentage
3. Nếu > 5%: Apply ML KNN inpainting
4. Nếu <= 5%: Apply spatial interpolation
5. Fallback fillna(0)

**Ưu điểm:**
- Cân bằng tốc độ và chất lượng
- Adaptive - chỉ dùng ML khi cần
- Hiệu quả với mọi cloud coverage

**Nhược điểm:**
- Phức tạp hơn classic
- Khó debug

**Khi nào dùng:** **Khuyến nghị cho production** - tự động chọn strategy phù hợp

---

## So sánh Performance

| Method | Tốc độ | Chất lượng | RAM | Yêu cầu |
|--------|--------|------------|-----|---------|
| classic | ⭐⭐⭐⭐ | ⭐⭐⭐ | Thấp | Không |
| temporal_only | ⭐⭐⭐⭐⭐ | ⭐⭐ | Thấp | Nhiều scenes |
| median_composite | ⭐⭐⭐ | ⭐⭐⭐⭐ | Thấp | >= 3 scenes |
| ml_knn | ⭐⭐ | ⭐⭐⭐⭐ | Trung bình | Đủ valid pixels |
| ml_rf | ⭐ | ⭐⭐⭐⭐⭐ | Cao | Đủ valid pixels |
| deep | ⭐ | ⭐⭐⭐⭐⭐ | Rất cao | Pretrained model + GPU |
| hybrid | ⭐⭐⭐ | ⭐⭐⭐⭐ | Trung bình | Không |

---

## Phát hiện mây (SCL)

Tất cả methods đều sử dụng SCL (Scene Classification Layer):

```python
# SCL values:
# 0: No data, 1: Saturated/Defective, 2: Dark Area Pixels
# 3: Cloud shadows, 4: Vegetation, 5: Not vegetated, 6: Water
# 7: Unclassified, 8: Cloud medium probability, 9: Cloud high probability
# 10: Thin cirrus, 11: Snow/Ice

cloud_mask = (scl == 3) | (scl == 8) | (scl == 9) | (scl == 10) | (scl == 11)
invalid_mask = (scl == 0) | (scl == 1)
full_mask = cloud_mask | invalid_mask
```

---

## Testing & Comparison

So sánh nhiều methods trên cùng dữ liệu:

```python
from cloud_removal import compare_methods

results = compare_methods(
    s2_data=s2_data,
    methods=["classic", "temporal_only", "ml_knn", "hybrid"]
)

for method, result in results.items():
    print(f"{method}: {result['remaining_nan_percent']:.2f}% NaN remaining")
```

---

## Khuyến nghị sử dụng

### Production (General)
```
cloud_removal_method: "hybrid"
```
- Cân bằng tốc độ và chất lượng
- Adaptive theo cloud coverage

### High Quality (Research)
```
cloud_removal_method: "ml_rf"
```
- Chất lượng tối đa
- Chấp nhận tốc độ chậm

### Fast Processing (Monitoring)
```
cloud_removal_method: "temporal_only"
```
- Cần nhiều scenes (>10)
- Ưu tiên tốc độ

### Low Cloud Coverage (<10%)
```
cloud_removal_method: "classic"
```
- Đơn giản, hiệu quả
- Ổn định, đã test kỹ

---

## Vị trí code

- **Module:** `cloud_removal.py` - Standalone cloud removal module
- **API Integration:** `api_server.py` - API endpoints và config
- **Documentation:** `CLOUD_PROCESSING.md` - Tài liệu này

---

## Phát triển tiếp

- [ ] Implement CNN autoencoder cho deep inpainting
- [ ] Add quality scoring system
- [ ] Optimize ML methods với Dask
- [ ] Add weighted temporal interpolation
- [ ] Support custom ML models