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:

GET /api/cloud-removal/methods

Response:

{
  "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:

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

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

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

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