README.md

---
license: openrail
datasets:
- Nj-1111/Glaucoma_Dataset
pipeline_tag: image-segmentation
---
# EyeeSEE — Glaucoma Segmentation Model

**Repository:** `Nj-1111/EyeeSEE`  
**Dataset:** [`Nj-1111/Glaucoma_Dataset`](https://huggingface.co/datasets/Nj-1111/Glaucoma_Dataset)  
**Demo:** [`Nj-1111/EyeeSEE` (Spaces)](https://huggingface.co/spaces/Nj-1111/EyeeSEE)

---

## Model Description

EyeeSEE is a U-Net segmentation model trained to delineate the **Optic Disc** and **Optic Cup** in retinal fundus photographs for automated glaucoma screening. It is the core inference engine of a Clinical Decision Support System (CDSS) that computes deterministic clinical metrics — vCDR, ISNT rim thickness, and three-tier risk stratification — from predicted segmentation masks.

Monte Carlo Dropout is used at inference time to produce a per-prediction uncertainty score, flagging low-confidence cases for clinical review.

---

## Model Architecture

| Component | Detail |
|---|---|
| Architecture | U-Net with skip connections |
| Input | Grayscale fundus image, 512 × 512 |
| Output | 3-class segmentation map (Background / Optic Disc / Optic Cup) |
| Base filters | 64 |
| Dropout | Dropout2d, rate = 0.1 |
| Parameters | ~31M |
| Uncertainty | Monte Carlo Dropout (N passes at inference) |

---

## Training

| Detail | Value |
|---|---|
| Dataset | Nj-1111/Glaucoma_Dataset |
| Training images | ~13,300 |
| Validation images | ~770 |
| Optimizer | Adam, lr = 5e-5 |
| Loss | 0.5 × Dice + 0.5 × Weighted CrossEntropy |
| Class weights | Background 0.1 · Disc 1.5 · Cup 3.0 |
| Hardware | Kaggle GPU (T4) |
| Framework | PyTorch 2.x |

---

## Dataset

**[`Nj-1111/Glaucoma_Dataset`](https://huggingface.co/datasets/Nj-1111/Glaucoma_Dataset)**

Curated from three public sources with a unified preprocessing pipeline:

| Source | Description |
|---|---|
| EyePACS | Large-scale diabetic retinopathy screening dataset |
| SMDG | Structured multi-disease glaucoma dataset |
| REFUGE2 | Retinal Fundus Glaucoma Challenge (segmentation reference) |

**Split:**

| Split | Images |
|---|---|
| Train | ~13,300 |
| Validation | ~770 |
| Test | ~770 |

Each image is labelled as **NRG** (Non-Referable Glaucoma / Normal) or **RG** (Referable Glaucoma).

---

## Clinical Metrics (Phase 3 Pipeline)

After segmentation, the following are computed deterministically:

**vCDR — Vertical Cup-to-Disc Ratio**  
Vertical diameter of cup ÷ vertical diameter of disc. Primary glaucoma screening metric.

| vCDR | Clinical Interpretation |
|---|---|
| < 0.65 | Healthy |
| 0.65 – 0.80 | Glaucoma Suspect |
| > 0.80 | High Risk |

**ISNT Rule**  
Neuro-retinal rim thickness measured in four quadrants. Healthy eyes satisfy: Inferior > Superior > Nasal > Temporal. Violation is an early indicator of glaucomatous damage.

**Risk Stratification**  
Three-tier output: Healthy · Glaucoma Suspect · High Risk.

---

## Checkpoints

Checkpoints are saved to `checkpoints/` during training and named:

```
checkpoints/checkpoint_epoch_NNN.pt
```

Each checkpoint contains model weights, optimiser state, scheduler state, validation metrics, and best validation loss.

To load the latest checkpoint for inference:

```python
from checkpoint_loader import load_model_for_inference
from model import UNet

model = UNet(in_channels=1, n_classes=3, base_filters=64, dropout=0.3)
model = load_model_for_inference(
    model=model,
    repo_id="Nj-1111/EyeeSEE",
    epoch=None,         # None = latest
    token="hf_..."
)
```

---

## Inference

### Via HuggingFace Spaces UI

Visit [huggingface.co/spaces/Nj-1111/EyeeSEE](https://huggingface.co/spaces/Nj-1111/EyeeSEE), upload a fundus image (JPEG or PNG), and click **Analyse**.

### Via Python Client

```python
from gradio_client import Client, handle_file

client = Client("Nj-1111/EyeeSEE")
result = client.predict(
    file_path=handle_file("fundus.jpg"),
    api_name="/analyse"
)

text_report = result[0]
pdf_path    = result[1]
print(text_report)
```

### Via REST API

```bash
# JSON report
curl -X POST https://nj-1111-eyeesee.hf.space/predict \
  -F "file=@fundus.jpg"

# PDF report
curl -X POST https://nj-1111-eyeesee.hf.space/predict/pdf \
  -F "file=@fundus.jpg" --output report.pdf
```

### Programmatic (Python)

```python
from phase3pipeline import Phase3Pipeline

pipeline = Phase3Pipeline(
    repo_id="Nj-1111/EyeeSEE",
    epoch=None,
    mc_passes=10,
    token="hf_..."
)

import cv2
image  = cv2.imread("fundus.jpg")
result = pipeline.run(image)

print(result["report"]["vcdr"])
print(result["report"]["risk_level"])
```

---

## Limitations

- Segmentation masks are trained on synthetic circular approximations of the disc and cup. Performance on pathological cases may be reduced until real ground-truth annotations are incorporated.
- vCDR thresholds are population-level estimates and do not account for disc size, ethnicity, or myopia.
- Eye laterality (nasal/temporal swap between left and right eyes) is not currently handled. ISNT values should be interpreted directionally with caution.
- This model has not been validated in a clinical trial. It is a research prototype.

---

## Intended Use

| Use | Status |
|---|---|
| Research and academic study | ✓ Intended |
| Preliminary screening assistance | ✓ Intended with supervision |
| Clinical diagnosis without ophthalmologist review | ✗ Not intended |
| Standalone medical device | ✗ Not intended |

---

## Disclaimer

> This model is a **research prototype** and is **NOT a certified medical device**.  
> All outputs must be validated by a qualified ophthalmologist before any clinical action is taken.  
> The authors accept no liability for clinical decisions made on the basis of this model's output.

---

## Citation

If you use this model or dataset in your research, please cite:

```
@misc{eyeesee2025,
  author    = {Nj-1111},
  title     = {EyeeSEE: Glaucoma Clinical Decision Support System},
  year      = {2025},
  publisher = {HuggingFace},
  url       = {https://huggingface.co/Nj-1111/EyeeSEE}
}
```

---