Official implementation of XDR-Net, a compact hybrid CNN-Transformer framework for automated diabetic retinopathy screening that combines CLAHE-based normalization, class-aware sampling, an EfficientNet backbone, and a lightweight single-layer self-attention bridge.

🎯 Key Achievement: 97.40% accuracy on APTOS 2019, outperforming Swin-T by +1.58% and ViT by +3.07%

Diabetic retinopathy (DR) is a leading cause of preventable blindness, characterized by subtle retinal lesions and ordinal progression of severity. Automated DR grading from fundus photographs faces critical challenges:

• Strong class imbalance with overrepresentation of healthy/mild cases
• Heterogeneous acquisition conditions (illumination, color, focus)
• Ambiguous boundaries between adjacent severity grades
• Need for interpretability in clinical deployment

Conventional CNNs capture local lesion patterns (microaneurysms, hemorrhages, exudates) but struggle to integrate global retinal context. Vision Transformers provide global reasoning but require massive datasets and heavy computation, limiting clinical deployment and weakening post-hoc explanations like Grad-CAM.

XDR-Net addresses these limitations through:

1. Hybrid Architecture: EfficientNet-B0 backbone + single-layer self-attention bridge
2. Robust Preprocessing: CLAHE-based normalization to handle acquisition variability
3. Balanced Optimization: Class-aware sampling with effective-number-based weighting
4. Clinical Interpretability: Grad-CAM on final convolutional block for lesion-focused heatmaps

Key Advantages:

• ✅ +1.58% accuracy improvement over Swin-T
• ✅ +3.07% accuracy improvement over ViT
• ✅ +5.75% Macro-F1 improvement over best baseline
• ✅ 6.7× smaller than Swin-T (4.22M vs 28.3M parameters)
• ✅ 5.7× faster than Swin-T (7.96ms vs 15.7ms latency)

Figure 1: XDR-Net architectural workflow showing preprocessing, feature extraction, attention bridge, and classification.

CLAHE Enhancement - Contrast-Limited Adaptive Histogram Equalization applied to luminance channel:

Figure 2: Effect of CLAHE preprocessing on fundus images, enhancing local contrast while preserving lesion details.

Pipeline Steps:

1. Circular crop centered on optic disc (removes black borders)
2. Resize to 384×384 pixels
3. Per-channel normalization (ImageNet statistics)
4. CLAHE on LAB luminance channel (clip limit τ = 2.0, tile size 8×8)

# Model Configuration
Backbone: EfficientNet-B0 (timm pretrained)
Output channels: 320
Spatial resolution: 12×12 (H'×W')
Parameters: 4.014M
FLOPs: 0.83G

Features:

• Compound scaling for efficient feature learning
• Depthwise separable convolutions
• Mobile inverted bottleneck (MBConv) blocks
• Pretrained on ImageNet for robust initialization

Single-layer Multi-Head Self-Attention (MHA):

# Attention Configuration
Number of tokens N_t = H' × W' = 12 × 12 = 144
Token dimension d = 320
Number of heads h = 4
Dimension per head d_h = 80
FFN expansion = 4
Total parameters: +0.205M

Mathematical Formulation:

Tokenization: T ∈ ℝ^(N_t × d), where each token represents a 32×32 patch

Multi-head attention:

Q, K, V = T·W_Q, T·W_K, T·W_V
Attention^(m) = softmax(Q^(m)·K^(m)ᵀ / √d_h) · V^(m)
Output = Concat(Attention^(1), ..., Attention^(h)) · W_O

Benefits:

• Captures long-range dependencies across retinal quadrants
• Detects global lesion distributions and symmetry
• Minimal computational overhead (O(N_t² · d) with small N_t)
• Complements local CNN features

Architecture:
- Global Average Pooling: ℝ^(144×320) → ℝ^320
- Layer Normalization
- Dropout (p=0.3)
- Linear: ℝ^320 → ℝ^5 (five DR grades)
- Softmax activation

• Size: 3,662 fundus images
• Classes: 5 DR severity levels (No DR, Mild, Moderate, Severe, Proliferative)
• Source: Community-level screening programs
• Characteristics: Heterogeneous illumination, focus, field-of-view
• Split: 1,857 train / 1,805 validation

• Size: 88,702 fundus images
• Classes: 5 DR severity levels
• Source: Multiple clinics and screening campaigns
• Characteristics: Extreme class imbalance, high domain shift
• Challenge: Largest public DR dataset with pronounced acquisition variability

• Size: 1,200 fundus images
• Classes: 5 DR severity levels
• Source: Clinical settings with controlled imaging
• Characteristics: High-quality, consistent illumination
• Reliability: Standard benchmark with expert annotations

• Size: 516 carefully curated images
• Classes: 5 DR severity levels + pixel-level lesion annotations
• Source: Clinical setting
• Special: Includes microaneurysms, hemorrhages, exudates annotations
• Value: Fine-grained recognition benchmark

APTOS 2019:

Figure 3: Confusion matrix for APTOS 2019 showing strong diagonal performance with minimal inter-class confusion.

EyePACS:

Figure 4: Confusion matrix for EyePACS dataset demonstrating robust performance on large-scale data.

IDRiD:

Figure 5: Confusion matrix for IDRiD showing accurate classification even with limited data.

Messidor:

Figure 6: Confusion matrix for Messidor dataset with high-quality clinical images.

Key Observations:

• Convergence achieved at epoch ~40-45
• Validation metrics closely track training (gap < 1%)
• No catastrophic overfitting despite class imbalance
• Smooth loss decay confirms stable gradient flow

We apply Gradient-weighted Class Activation Mapping (Grad-CAM) on the final convolutional block to generate class-discriminative heatmaps that highlight decision-relevant retinal regions.

EyePACS Dataset:

Figure 8: Grad-CAM visualizations on EyePACS showing attention on pathological lesions across DR severity grades.

APTOS 2019 Dataset:

Figure 9: Grad-CAM visualizations on APTOS 2019 demonstrating focus on microaneurysms, hemorrhages, and exudates.

IDRiD Dataset:

Figure 10: Grad-CAM visualizations on IDRiD showing precise localization of subtle lesions in fine-grained cases.

Quantitative Analysis:

• 94.7% of Grad-CAM activations co-localize with expert-annotated lesion regions
• Average IoU with ground truth: 0.78
• Model attention aligns with phytopathological knowledge across all severity grades

What the Model Sees:

• ✅ Microaneurysms (small red dots)
• ✅ Hemorrhages (red blotches)
• ✅ Hard exudates (yellow/white deposits)
• ✅ Soft exudates (cotton-wool spots)
• ✅ Neovascularization (abnormal vessel growth)

Systematic evaluation of each component's contribution on APTOS 2019:

1. CLAHE Preprocessing (+0.61% Macro-F1)

   • Enhances lesion visibility
   • Stabilizes performance across acquisition conditions
   • Zero computational overhead

2. Class Reweighting (-5.24% Macro-F1 when isolated)

   • Destabilizes optimization when used alone
   • Critical when combined with attention bridge
   • Addresses severe class imbalance (50% No DR in APTOS)

3. Attention Bridge (+6.78% Macro-F1)

   • Largest single improvement
   • Enables global context modeling
   • Only +0.205M parameters, negligible FLOPs

4. Test-Time Augmentation (+30.66% Macro-F1)

   • Dramatic performance boost
   • Averages predictions over M=4 augmented views
   • Reduces variance in predictions

Hardware:
  GPU: NVIDIA RTX 3090 (24GB VRAM)
  CPU: Intel Xeon (multi-core)
  RAM: ≥16GB
  Storage: SSD recommended

Software:
  Python: 3.10+
  PyTorch: 2.0+
  CUDA: 11.3+
  Mixed Precision: Enabled (AMP)

Data:
  Image size: 384 × 384
  Batch size: 32
  Train split: 80%
  Validation split: 20%
  Patient-level split: Enforced

Augmentation (Training Only):
  Horizontal flip: p=0.5
  Random rotation: ±15°
  Random resize/crop: scale=(0.9, 1.1)
  Color jitter: brightness=0.2, contrast=0.2
  Gaussian blur: σ=0.5, p=0.3

Optimization:
  Optimizer: AdamW
  β₁, β₂: 0.9, 0.999
  Initial LR: 3×10⁻⁴
  Schedule: Cosine decay
  Weight decay: 1×10⁻⁴
  Gradient clipping: ||g||₂ ≤ 1.0
  
Loss:
  Type: Cross-entropy
  Label smoothing: ε=0.1
  Class weighting: Effective-number based
  β (APTOS): 0.999
  β (EyePACS): 0.9999
  β (Messidor/IDRiD): 0.995

Regularization:
  Dropout: p=0.3 (classification head)
  Early stopping: patience=15 epochs
  Metric: Validation Macro-F1

Inference:
  TTA: M=4 (flips + crops)
  Temperature scaling: T=1.5
  Mixed precision: float16

git clone https://github.com/ItsCodeBakery/XDR-NET.git
cd XDR-NET

# Using conda (recommended)
conda create -n xdrnet python=3.10
conda activate xdrnet

# Or using venv
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

pip install -r requirements.txt

requirements.txt:

torch>=2.0.0
torchvision>=0.15.0
timm>=0.9.0
numpy>=1.24.0
pandas>=2.0.0
scikit-learn>=1.3.0
opencv-python>=4.8.0
albumentations>=1.3.0
matplotlib>=3.7.0
seaborn>=0.12.0
tqdm>=4.65.0
tensorboard>=2.13.0
Pillow>=10.0.0
scipy>=1.11.0

APTOS 2019:

# Kaggle CLI (requires kaggle.json)
kaggle competitions download -c aptos2019-blindness-detection
unzip aptos2019-blindness-detection.zip -d data/APTOS2019/

EyePACS:

kaggle datasets download -d dreamer07/eyepacs
unzip eyepacs.zip -d data/EyePACS/

Messidor:

• Download from: https://www.adcis.net/en/third-party/messidor/
• Place in data/Messidor/

IDRiD:

• Download from: https://ieee-dataport.org/open-access/indian-diabetic-retinopathy-image-dataset-idrid
• Place in data/IDRiD/

XDR-NET/
├── data/
│   ├── APTOS2019/
│   │   ├── train_images/
│   │   ├── test_images/
│   │   └── train.csv
│   ├── EyePACS/
│   │   ├── train/
│   │   └── trainLabels.csv
│   ├── Messidor/
│   │   └── images/
│   └── IDRiD/
│       ├── images/
│       └── labels.csv
├── Proposed Methodology/
│   ├── code/
│   │   ├── train.py
│   │   ├── test.py
│   │   ├── model.py
│   │   └── utils.py
│   └── plots/
├── BaseLineExperement/
│   ├── ResNet/
│   ├── ConvNeXt/
│   └── ...
├── checkpoints/
├── logs/
└── requirements.txt

cd "Proposed Methodology/code"

# Train on APTOS 2019
python train.py \
    --dataset aptos2019 \
    --data_path ../../data/APTOS2019 \
    --batch_size 32 \
    --epochs 100 \
    --lr 3e-4 \
    --output_dir ../../checkpoints/aptos

# Train on EyePACS
python train.py \
    --dataset eyepacs \
    --data_path ../../data/EyePACS \
    --batch_size 32 \
    --epochs 100 \
    --beta 0.9999  # Higher β for extreme imbalance

# Evaluate trained model
python test.py \
    --checkpoint ../../checkpoints/aptos/best_model.pth \
    --dataset aptos2019 \
    --data_path ../../data/APTOS2019 \
    --tta  # Enable test-time augmentation

import torch
from model import XDRNet
from utils import preprocess_image
from PIL import Image

# Load model
model = XDRNet(num_classes=5)
checkpoint = torch.load('checkpoints/best_model.pth')
model.load_state_dict(checkpoint['model_state_dict'])
model.eval()

# Load and preprocess image
image = Image.open('path/to/fundus.jpg')
input_tensor = preprocess_image(image)

# Predict
with torch.no_grad():
    logits = model(input_tensor.unsqueeze(0))
    probs = torch.softmax(logits, dim=1)
    pred_class = torch.argmax(probs, dim=1).item()
    confidence = probs[0, pred_class].item()

dr_grades = ['No DR', 'Mild', 'Moderate', 'Severe', 'Proliferative DR']
print(f"Prediction: {dr_grades[pred_class]}")
print(f"Confidence: {confidence:.2%}")

from utils import generate_gradcam

# Generate Grad-CAM visualization
gradcam_img = generate_gradcam(
    model=model,
    image=input_tensor,
    target_class=pred_class,
    layer_name='features'  # Final conv block
)

# Save visualization
gradcam_img.save('gradcam_output.png')

XDR-NET/
│
├── Proposed Methodology/
│   ├── code/
│   │   ├── train.py              # Training script
│   │   ├── test.py               # Evaluation script
│   │   ├── model.py              # XDR-Net architecture
│   │   ├── dataset.py            # Dataset loaders
│   │   ├── utils.py              # Utilities (augmentation, metrics)
│   │   ├── gradcam.py            # Grad-CAM implementation
│   │   └── config.py             # Configuration management
│   │
│   └── plots/                    # Result visualizations
│       ├── METHODLOGY.png
│       ├── ClahePrep.png
│       ├── confusion_matrix_*.png
│       ├── accuracy_curve.png
│       ├── f1_curve.png
│       ├── loss_curve.png
│       └── *_gradcam.png
│
├── BaseLineExperement/
│   ├── ResNet18/code/
│   ├── ResNet50/code/
│   ├── ConvNeXt/code/
│   └── ...
│
├── data/                         # Dataset directory (not in repo)
├── checkpoints/                  # Model checkpoints
├── logs/                         # TensorBoard logs
├── requirements.txt
├── README.md
└── LICENSE

All experiments use fixed seeds for reproducibility:

SEED = 42
torch.manual_seed(SEED)
torch.cuda.manual_seed(SEED)
np.random.seed(SEED)
random.seed(SEED)
torch.backends.cudnn.deterministic = True
torch.backends.cudnn.benchmark = False

Patient-level splits are enforced to prevent data leakage:

• Train/Validation split: 80/20
• Test set: Separate when available
• Stratified sampling maintains class distribution

Key hyperparameters with tested ranges:

1. Novel Hybrid Architecture

   • First single-layer attention bridge for DR detection
   • Balances local CNN features with global transformer context
   • 6.7× more compact than Swin-T while outperforming it

2. Principled Imbalance Handling

   • Effective-number-based class weighting
   • Dual mechanism: sampling bias + loss reweighting
   • Consistently improves macro-F1 across all datasets

3. Robust Preprocessing Pipeline

   • CLAHE-based contrast enhancement
   • Preserves lesion details while reducing acquisition variability
   • Generalizes across heterogeneous imaging conditions

4. Clinical Interpretability

   • Grad-CAM co-localizes with expert-annotated lesions (94.7% IoU)
   • Provides transparent decision support for clinicians
   • Validates attention on pathologically meaningful structures

5. Comprehensive Evaluation

   • Four benchmark datasets (APTOS, EyePACS, Messidor, IDRiD)
   • Systematic ablation study
   • Comparison with 10+ baseline architectures
   • State-of-the-art performance on all benchmarks

We thank:

• Kaggle for hosting APTOS 2019 and EyePACS datasets
• ADCIS for the Messidor database
• IEEE DataPort for the IDRiD dataset
• The open-source community for PyTorch and timm

• Uncertainty Quantification: Bayesian deep learning for prediction confidence
• Multimodal Integration: Combine fundus + OCT imaging
• Mobile Deployment: TFLite/ONNX export for edge devices
• Ordinal Regression: Exploit ordinal nature of DR severity
• Few-Shot Learning: Adapt to rare DR subtypes
• Temporal Modeling: Track disease progression over time
• Fairness Analysis: Evaluate performance across demographics

This project is licensed under the MIT License:

MIT License

Copyright (c) 2025 XDR-Net Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

• Issues: GitHub Issues
• Pull Requests: Contributions welcome!
• Email: shayan.ali@imsciences.edu.pk

Status: 🟡 Paper Under Review | 🟢 Code Available | 🔵 Active Development

Last Updated: December 2025