👁️ Glaucoma Fundus - Cup-to-disc ratio Assessment for Retinal Evaluation (GF-CARE)

Sistem End-to-End Deep Learning untuk deteksi dini Glaukoma melalui segmentasi Optic Disc (OD) dan Optic Cup (OC) pada citra fundus retina. Sistem ini menghitung rasio Cup-to-Disc (CDR) secara otomatis.

✨ Fitur Utama

• Two-Stage Pipeline: Ekstraksi Region of Interest (ROI) secara biner, dilanjutkan dengan segmentasi Multiclass (OD & OC) untuk akurasi maksimal.
• Config-Driven Architecture: Seluruh hyperparameter (Epochs, Learning Rate, arsitektur Backbone) dikendalikan penuh melalui file YAML, tanpa perlu mengubah source code.
• Zero Data Leakage: Pipeline evaluasi dijamin bebas dari kebocoran data dengan sistem pelacakan berbasis CSV.
• Clinical Metrics: Evaluasi tidak hanya sebatas metrik piksel (IoU/Dice), tetapi langsung dihadapkan dengan perhitungan Vertical CDR, Horizontal CDR, dan Area CDR dari dokter spesialis mata (Ground Truth).
• Web Deployment Ready: Terintegrasi langsung dengan antarmuka web berbasis Flask dan Tailwind CSS untuk demonstrasi real-time.

📂 Arsitektur Direktori

.
├── configs/               # File konfigurasi eksperimen (.yaml)
├── data/                  # Root dataset (tidak di-commit ke Git)
│   ├── raw/               # Citra mentah & Ground Truth CSV Dokter
│   └── processed/         # Hasil preprocessing & splitting
├── outputs/               # Model tersimpan, log training, & hasil evaluasi
├── scripts/               # Script eksekusi utama (Training, Evaluasi, Data Prep)
├── src/                   # Core engine & modul OOP
│   ├── core/              # Custom Losses, Metrics, Trainer, Clinical Analyzer
│   ├── datasets/          # Dataloader, Augmentation, Preprocessing
│   ├── models/            # U-Net Builder (Standard & Pretrained)
│   └── utils/             # Tools pembantu (Seeding, Config Loader, Custom Objs, Data IO)
├── webapp/                # Flask Web Application
└── requirements.txt       # Daftar dependensi Python

⚙️ Persiapan & Instalasi

1. Clone repositori ini:

git clone [https://github.com/TjengIvanCahyadi/gf-care.git](https://github.com/TjengIvanCahyadi/gf-care.git)
cd gf-care

2. Buat virtual environment (Sangat disarankan) dan install dependensi:

python -m venv venv
source venv/bin/activate  # Untuk Windows: venv\Scripts\activate
pip install -r requirements.txt

🖼️ Aturan Struktur Dataset

Sistem ini menggunakan aturan I/O ketat untuk menghindari bug.

1. Format Citra (Image & Mask)

Pastikan dataset disusun dengan format berikut di dalam folder data/raw/images/ dan data/raw/masks/:

• Nama file gambar dan mask wajib persis sama.
• Ekstensi gambar wajib .jpg atau .jpeg.
• Ekstensi mask wajib .png.
• Contoh: images/pasien_001.jpg berpasangan dengan masks/pasien_001.png

2. Format CSV Ground Truth Klinis

Untuk menjalankan evaluasi klinis (evaluate_cdr.py), file CSV groundtruth cdr (contoh: data/cdr_groundtruth.csv) wajib memiliki kolom-kolom berikut (perhatikan kapitalisasinya):

• Patient ID : ID unik pasien (misal: P001). Digunakan untuk mencocokkan nama file citra.
• Laterality : Mata kanan atau kiri (misal: l / r).
• Diagnose : Diagnosis medis (0 untuk normal dan 1 untuk glaukoma).
• vCDR : Nilai Vertical Cup-to-Disc Ratio (Gunakan titik untuk desimal, misal: 0.65).
• hCDR : Nilai Horizontal Cup-to-Disc Ratio.
• Area CDR : Nilai Rasio Luas Area.

🚀 Panduan Penggunaan (Pipeline)

1. Preprocessing & Splitting Data

Jalankan preprocessing secara offline untuk mempercepat dataloader, kemudian pecah data menjadi Train/Val/Test.

# Preprocessing
python -m scripts.offline_processor --raw_dir data/raw --processed_dir data/processed --target_size 256

# Splitting Data (Pilih mode: random atau kfold)
python -m scripts.split_data --processed_dir data/processed --seed 42 random --train_ratio 0.70 --val_ratio 0.15 --test_ratio 0.15

2. Training Model

Semua konfigurasi diatur di dalam file configs/train_roi.yaml atau configs/train_main.yaml.

# Training Model ROI (Binary)
python -m scripts.train --config configs/train_roi.yaml

# Training Model Main (Multiclass)
python -m scripts.train --config configs/train_main.yaml

3. Evaluasi & Analisis Klinis (CDR)

# Evaluasi Standar
python -m scripts.evaluate \
  --config configs/train_main.yaml \
  --model_path outputs/fundus_main_.../models/model_RESNET50V2_random.keras

# Evaluasi Klinis CDR (Menghitung Mean Absolute Error dengan data Dokter)
python -m scripts.evaluate_cdr \
  --roi_config configs/train_roi.yaml \
  --roi_model outputs/fundus_roi_.../models/model_RESNET50V2_random.keras \
  --main_config configs/train_main.yaml \
  --main_model outputs/fundus_main_.../models/model_RESNET50V2_random.keras \
  --gt_csv data/groundtruth_clinical.csv

4. Menjalankan Web Application (Flask)

Aplikasi web disiapkan untuk mendemonstrasikan sistem secara langsung di peramban (browser). Pastikan untuk memperbarui path ROI_DIR dan MAIN_DIR di dalam file webapp/app.py sesuai dengan folder output model terbaik Anda.

# Jalankan server
flask --app webapp.app run --debug

Akses http://127.0.0.1:5000 di peramban Anda.

🔬 Tech Stack

• TensorFlow / Keras 3 (Deep Learning Framework)
• Albumentations (Data Augmentation)
• OpenCV & NumPy (Image Processing)
• Flask & Tailwind CSS (Web Interface)