"Bridging Computer Vision, Biophysical Modeling, and Clinical Ophthalmology to Eradicate Preventable Diabetic Blindness."
Full Video Walkthrough & Presentation:
🔗 https://drive.google.com/file/d/1iIu_hFnGv9Qd7C7yrte3tSrKxbx1NjUM/view?usp=sharing
Includes live platform demonstration, deep learning inference, Grad-CAM attention heatmaps, automated triage scheduling, and Simulink clinical capacity modeling.
- Important Medical Disclaimer
- Executive Summary & Problem Statement
- Key Innovations
- System Architecture
- AI & Computer Vision Diagnostic Pipeline
- Automated Clinical Triage & Specialist Referral
- MATLAB & Simulink Healthcare Modeling
- Validated Clinical Datasets
- Database & Cloud Infrastructure (Supabase + SQLite)
- Technology Stack
- Installation & Getting Started
- REST API Documentation
- Verification & Quality Assurance
- License
Important
OcuPulse is an assistive medical AI platform designed for clinical research, automated triage, and telemedicine screening. It is engineered to assist healthcare providers and optometrists in rapidly detecting diabetic retinopathy and microvascular abnormalities. It is not intended to replace direct professional clinical evaluation. Final diagnostic and treatment determinations must always be confirmed by a licensed ophthalmologist or retina specialist.
Diabetic Retinopathy (DR) is the leading cause of preventable blindness among working-age adults globally, impacting over 100 million individuals. Early detection and timely intervention can prevent up to 95% of vision loss.
- Severe Specialist Deficit: In low- and middle-income regions, the ratio of ophthalmologists to patients often exceeds 1:100,000, creating months-long waiting lists for routine screening.
-
Subjectivity & Human Fatigue: Manual grading of fundus photographs across high-volume screening camps exhibits high inter-observer variability (
$\kappa \approx 0.65-0.75$ ). - Black-Box AI Trust Deficit: Standard end-to-end deep neural networks often fail to explain why an image was classified as diseased and suffer from false-positive hallucinations on artifact-laden normal retinas.
- Disjointed Referral Loops: Traditional screening programs lack automated closing loops—patients identified with vision-threatening disease frequently drop out before obtaining an emergency appointment.
OcuPulse resolves these challenges by introducing a neuro-symbolic, biophysically-grounded screening pipeline that unifies:
- Deep convolutional neural networks calibrated to the International Clinical Diabetic Retinopathy (ICDR) standard.
- Deterministic biophysical lesion gating that cross-examines microvascular anomalies (microaneurysms, hemorrhages, hard/soft exudates, neovascularization).
- Explainable AI (Grad-CAM) highlighting precise anatomical regions of concern.
-
Automated clinical triage dispatch that auto-schedules doctor appointments for critical patients (ICDR
$\ge 2$ ). - Simulink queue-theoretic capacity modeling to optimize hospital throughput and prevent resource saturation.
- 🧠 Dual-Engine Diagnostic Architecture: Combines an EfficientNet-B3 deep convolutional network with deterministic lesion-detection rules, ensuring high sensitivity while eliminating false-positive referrals on clean scans.
- 🔬 Clinical Lesion-Gated Prior: Enforces AAO/ICDR guidelines—retinas exhibiting zero microvascular lesions are strictly reconciled as Grade 0 (No DR) with high confidence (
$98.5%$ ), protecting healthy individuals from unnecessary emergency referrals. - 👁️ Visual Explainability (Grad-CAM): Generates high-resolution saliency maps overlaid on fundus structures so clinicians can verify whether neural attention aligns with true pathological lesions.
- 📐 Sub-Pixel Microvascular Morphometry: Computes objective structural biomarkers including vessel density, fractal dimension (box-counting complexity), vessel caliber, skeleton tortuosity, and bifurcation topology.
- 🏥 Closed-Loop Emergency Scheduling: When referable disease (ICDR Grade 2, 3, or 4) is identified, the platform automatically schedules an emergency consultation with available ophthalmologists, tracking urgency, priority level, and clinical justification.
- 📈 Simulink Telemedicine Queue Modeling: Integrates MATLAB/Simulink stateflow models (
.slx) to simulate patient flow, network latency, edge-vs-cloud compute tradeoffs, and hospital specialist load balancing. - ☁️ Resilient Cloud Persistence: High-availability database layer utilizing Supabase PostgreSQL (with pooled connections) with automatic seamless fallback to local SQLite for offline/remote clinic operations.
flowchart TD
subgraph FrontendPresentationLayer [Client Layer - React 18 + Vite + TypeScript]
GlassUI[Glassmorphic Responsive UI]
SplitSlider[Interactive Before/After Image Slider]
VisualizerGrid[6-Stage Visualizer Grid - Masks, Heatmaps, Skeletons]
TriageScheduler[Automated Triage & Scheduling Dashboard]
SimulinkDashboard[Simulink Telemetry & Resource Optimiser]
end
FrontendPresentationLayer -->|Encrypted HTTPS / REST API| FastAPIServices
subgraph BackendCoreLayer [Backend Services - FastAPI + Python + SQLite]
AnalyzeRoute[/api/analyze - Fundus Ingestion/]
SimulinkRoute[/api/simulink - Queue & Throughput Simulation/]
ReportRoute[/api/report - Clinical PDF Generator/]
TriageEngine[Automated Risk Stratification Engine]
end
BackendCoreLayer --> ProcessingPipeline
subgraph DiagnosticPipelineLayer [Computer Vision & AI Pipeline]
Preprocess[Green Channel Extraction & CLAHE Contrast]
SegmentEngine[Multi-Scale Vessel Segmentation]
FeatureExtraction[6 Biomarker Topology Extractor]
QualityAssessor[SNR & Artifact Quality Filter]
Preprocess --> SegmentEngine --> FeatureExtraction --> QualityAssessor
end
OCUPULSE SYSTEM TOPOLOGY
┌──────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ CLIENT LAYER (React 18 + Vite + TS) │
│ • Modern Glassmorphic Dark UI • Multi-Stage Live Processing Stepper │
│ • Interactive Before/After Split Slider • 6-Stage Visualizer Grid (Masks, Heatmaps, Skeletons) │
│ • Real-Time Recharts Telemetry Charts • Automated Triage & Appointment Scheduling Dashboard │
│ • MATLAB/Simulink Interactive Simulator • Comprehensive PDF Clinical Report Generation │
└────────────────────────────────────────────────────┬─────────────────────────────────────────────────────┘
│ HTTPS / REST & WebSockets
▼
┌──────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ BACKEND ENGINE (FastAPI / Uvicorn) │
│ • REST API Controllers (/api/analyze, /api/appointments, /api/reports, /api/history) │
│ • Image Validation & Quality Assurance Gate (FOV verification, illumination, sharpness) │
│ • Dual-Database ORM Router (Supabase PostgreSQL / Offline SQLite Fallback) │
└────────────────────────┬──────────────────────────────────────────────────┬──────────────────────────────┘
│ │
▼ ▼
┌──────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────┐
│ AI & COMPUTER VISION SUBSYSTEM │ │ MATLAB & SIMULINK SUBSYSTEM │
│ │ │ │
│ [Raw Fundus] ──► [Green Channel + CLAHE] │ │ • screening_pipeline.slx (Edge vs Cloud Model) │
│ │ │ │ • resource_optimiser.slx (Queue Optimization) │
│ ├─► [EfficientNet-B3 Deep Classifier] │ │ • telemedicine_workflow.slx (Clinic Triage) │
│ │ │ │ │ • analyse_retina.m (Biophysical Biomarkers) │
│ │ ▼ │ │ • fractal_analytics.m (Box-Counting Dimension) │
│ ├─► [Grad-CAM Attention Heatmap] │ │ • lesion_quantification.m (MA/HE/EX Detect) │
│ │ │ └─────────────────────────────────────────────────┘
│ ├─► [Biophysical Lesion Detection] │
│ │ (Microaneurysms, Exudates, Hemorrhages│
│ │ │
│ ▼ │
│ [Clinical Lesion-Gated Reconciliation Engine] │
│ │ │
│ ├─► [Zhang-Suen Centerline Skeletonizer] │
│ │ │
│ ▼ │
│ [Topological & Geometric Biomarker Extractor] │
│ (Vessel Density, Tortuosity, Caliber, Fractal) │
└────────────────────────┬─────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ CLINICAL ACTION & PERSISTENCE LAYER │
│ • ICDR Scale Determination (Grade 0: Normal ──► Grade 4: Proliferative DR) │
│ • Referral Gate: If Grade >= 2 & Referable ──► Auto-Book Emergency Specialist Appointment │
│ • Supabase Enterprise Cloud DB: Encrypted storage of patient metadata, metrics, and appointment records │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────┘
The deep learning classifier uses an EfficientNet-B3 backbone pre-trained on ImageNet and fine-tuned on multi-center retinal fundus corpora. EfficientNet-B3 compounds depth, width, and resolution scaling, providing optimal feature extraction for fine vascular lesions with modest parameter count (
Grade 0 (No DR) Grade 1 (Mild) Grade 2 (Moderate) Grade 3 (Severe) Grade 4 (PDR)
┌─────────────────┐ ┌──────────────────┐ ┌───────────────────┐ ┌────────────────────┐ ┌──────────────────┐
│ • Zero lesions │ │ • Microaneurysms │ │ • More than MAs │ │ • 4-2-1 Rule: │ │ • Neovascular- │
│ • Healthy retina│ ──► │ only (<= 3) │ ──► │ • Hard exudates │ ──► │ >20 intraretinal │ ──► │ ization │
│ • Non-referable │ │ • Non-referable │ │ • Blot hemorrhage │ │ hemorrhages/quad │ │ • Vitreous bleed │
│ • Routine check │ │ • 12-mo review │ │ • Refer to Doctor │ │ • Urgent Referral │ │ • Emergency Care │
└─────────────────┘ └──────────────────┘ └───────────────────┘ └────────────────────┘ └──────────────────┘
Deep learning classifiers alone can occasionally produce false positives due to illumination gradients or camera artifacts. In clinical ophthalmology, Diabetic Retinopathy cannot exist without verifiable microvascular lesions.
OcuPulse implements a Biophysical Prior Reconciler:
-
Zero Lesions Check: If the biophysical lesion detector counts
$0$ microaneurysms,$0$ exudates,$0$ hemorrhages, and$0$ neovascular regions:$$\text{Reconciled Grade} = \text{Grade 0 (No DR)}, \quad \text{Confidence} = 98.5%, \quad \text{Referable} = \text{False}$$ -
Mild Microvascular Stage: If isolated microaneurysms are detected (
$\le 3$ ) without hemorrhages/exudates:$$\text{Reconciled Grade} = \text{Grade 1 (Mild NPDR)}, \quad \text{Referable} = \text{False}$$ -
Moderate / Severe Stage: If
$\ge 5$ microaneurysms, exudates, or hemorrhages are confirmed:$$\text{Reconciled Grade} \ge \text{Grade 2 (Moderate+ NPDR)}, \quad \text{Referable} = \text{True}, \quad \text{Trigger Appointment} = \text{True}$$
This hybrid neuro-symbolic mechanism guarantees zero false-positive emergency appointments on clean retinas.
To provide transparency, OcuPulse generates Gradient-Weighted Class Activation Mapping (Grad-CAM) from the final convolutional layer of EfficientNet-B3:
The resulting continuous heatmap highlights the specific microvascular patches driving the model's classification, rendering AI reasoning fully inspectable by the ophthalmologist.
[Raw Fundus] ──► [Circular FOV Masking] ──► [Green Channel Selection (λ ~ 540-570nm)]
│
▼
[CLAHE Dynamic Contrast Amplification] ──► [Multi-Scale Frangi Hessian Ridge Filters]
│
▼
[Adaptive Gaussian Thresholding] ──► [Binary Vessel Tree Mask]
│
▼
[Zhang-Suen Morphological Thinning] ──► [Single-Pixel Centerline Skeleton]
│
▼
[8-Connected Graph Topology Traversal] ──► [Bifurcations, Endpoints, Tortuosity Index]
- Spectral Channel Isolation: Extracts the green channel where ocular hemoglobin exhibits peak light absorption, maximizing contrast between blood vessels and the choroidal background.
- Circular FOV Mask: Automatically detects the round retinal boundary, eliminating flash perimeter artifacts.
- CLAHE Enhancement: Contrast Limited Adaptive Histogram Equalization prevents over-amplification in bright macular regions while exposing faint peripheral capillaries.
-
Frangi Hessian Filter: Computes eigenvalues of the local Hessian matrix
$(\lambda_1, \lambda_2)$ across multiple scales ($\sigma \in [1.0, 3.0]$ ) to selectively amplify tubular vascular structures while suppressing planar and spherical noise. - Zhang-Suen Skeletonization: Iteratively thins the segmented vessels to a 1-pixel-wide topological centerline without altering connectivity.
| Biomarker Metric | Clinical Formula / Method | Diagnostic Relevance |
|---|---|---|
| Vessel Density (%) | Ischemic dropout, vascular rarefaction in advanced diabetes | |
| Centerline Length (px) | Total perfused vascular arborization | |
| Branch Points (Bifurcations) | 8-neighbor connectivity |
Microvascular pruning or aberrant neovascular budding |
| Terminal Endpoints | 8-neighbor connectivity |
Capillary bed non-perfusion and terminal pruning |
| Mean Caliber Index (px) | Arteriolar narrowing / venular dilation (AV ratio marker) | |
| Tortuosity Index | Elevated vascular shear stress, hypertension, and DR progression | |
| Fractal Dimension ( |
Box-counting method: |
Global vascular complexity loss ( |
| Image Quality Grade | Laplacian variance + Michelson contrast | Pre-screening quality assurance preventing misdiagnosis |
When an analysis reveals referable disease (
DIAGNOSTIC TRIAGE DECISION TREE
[Analysis Complete]
│
Is ICDR Grade >= 2 AND
Referable == True?
│
┌────────────────┴────────────────┐
YES NO
│ │
▼ ▼
[Critical Triage Active] [Routine Care Pathway]
• Assign Priority Level • Annual/Biennial Screening
• Match Available Doctor • Self-Care Recommendations
• Allocate Hospital Slot • No Referral Required
• Persist to DB Appointments • Return Clean Status
• Render in Appointments UI
- Patient Identifier: Auto-assigned or linked to existing health ID.
- Assigned Specialist: Matches verified ophthalmologists (e.g., Dr. Rajesh Sharma, MD (Retina)).
- Scheduled Time: Automatically provisioned within a 48-hour critical window.
- Priority Tier:
URGENTfor Grade 2 (Moderate),EMERGENCYfor Grade 3-4 (Severe/PDR). - Clinical Justification: Clear documentation of detected microaneurysms, hemorrhages, and vascular density reductions for immediate review.
OcuPulse bridges clinical AI with industrial systems engineering by integrating MATLAB algorithms and Simulink models:
screening_pipeline.slx: Models multi-tier edge-vs-cloud screening throughput, network latency under variable bandwidth, and packet loss handling in rural telemedicine camps.resource_optimiser.slx: Queue-theoretic discrete-event simulation optimizing ophthalmologist review loads, triage queue wait times, and emergency bed allocation.telemedicine_workflow.slx: End-to-end operational stateflow model illustrating patient ingestion, automated grading, tele-consultation dispatch, and follow-up closure.
analyse_retina.m: Complete biophysical feature extraction pipeline in pure MATLAB.FrangFilter2D.m: High-performance 2D multiscale vesselness filter implementation.fractal_dimension.m: Multi-box counting grid evaluation of vascular complexity.lesion_detection.m: Mathematical morphology for microaneurysm and exudate segmentation.dr_grading.m&severity_grading.m: MATLAB decision tree severity classifier.
The models and algorithms within OcuPulse are designed and validated against international gold-standard ophthalmic databases:
| Dataset | Sample Volume | Resolution | Ground Truth Annotations | Primary Usage |
|---|---|---|---|---|
| APTOS 2019 | 3,662 fundus scans | Multi-resolution | 5-class ICDR severity grades | Deep learning classifier fine-tuning |
| Kaggle DR 2750 | 2,750 fundus scans | Multi-resolution | 5-class (Healthy: 1,000, Mild: 370, Moderate: 900, Severe: 190, PDR: 290) | Class-imbalance evaluation & ordinal grading |
| DRIVE | 40 fundus images | Dual expert manual vessel segmentations | Vessel segmentation & skeleton accuracy | |
| IDRiD | 516 images | Pixel-level lesion masks (MA, HE, EX, SE) | Biophysical lesion detection calibration | |
| Messidor-2 | 1,200 images | DR grade and Diabetic Macular Edema (DME) | Cross-dataset generalizability testing |
OcuPulse features an enterprise hybrid persistence architecture:
PERSISTENCE ROUTER
│
Is DATABASE_URL (Supabase) Available?
│
┌─────────────────┴─────────────────┐
YES NO
│ │
▼ ▼
[Supabase PostgreSQL] [Local SQLite Engine]
• Cloud-Hosted Relational DB • Zero-Config Local File
• Session Pooler (Port 5432/6543) • Offline Remote Clinic Capable
• Auto-Migrated Schema • Seamless Dev Fallback
analyses/images: Stores scan telemetry, quality scores, ICDR grade, confidence, fractal dimension, vessel density, and full biomarker JSON payloads.appointments: Manages patient triage bookings, physician assignments, urgency status (SCHEDULED,COMPLETED), and scheduled appointment timestamps.
- Core: React 18.3, TypeScript 5.4, Vite
- Styling: Tailwind CSS 3.4, Lucide React Icons
- Visualizations: Recharts (interactive distributions & metrics), Canvas-based Zoom & Pan Viewer
- Document Engine: Custom HTML5/CSS Print & PDF Clinical Report Renderer
- Framework: FastAPI (Python 3.10+), Uvicorn ASGI
- Deep Learning: PyTorch 2.0+, Torchvision, EfficientNet-B3
- Image Processing: OpenCV (cv2), SciPy, NumPy, Scikit-Image
- Database ORM: SQLAlchemy 2.0, Psycopg2-binary (PostgreSQL / Supabase), SQLite3
- Validation: Pydantic v2 schemas
- MathWorks: MATLAB R2022b+, Simulink, Stateflow
- Python: Version
3.10,3.11, or3.12 - Node.js: Version
18.0or higher - Git: Installed and configured
Clone the repository and run the automated launcher:
# 1. Clone repository
git clone https://github.com/shrikargs7-cloud/ocupulse-dr.git
cd ocupulse-dr
# 2. Run the unified launcher script (macOS / Linux)
chmod +x run_ocupulse.sh
./run_ocupulse.shFor Windows users:
run_ocupulse.batThe script automatically sets up the Python virtual environment, installs backend and frontend dependencies, starts the FastAPI server on port 8000, and launches the Vite client on port 5173.
Copy the provided environment template:
cp .env.example .env(Optional: Open .env and fill in your Supabase PostgreSQL connection URI if connecting to the cloud).
# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate # On Windows: .\venv\Scripts\activate
# Install dependencies
pip install -r backend/requirements.txt
# Start backend server
uvicorn backend.app.main:app --host 0.0.0.0 --port 8000 --reload# Open a new terminal
cd frontend
# Install node dependencies
npm install
# Start Vite dev server
npm run devOpen your browser at http://localhost:5173. Interactive API docs will be live at http://localhost:8000/docs.
| Method | Endpoint | Description | Request Type |
|---|---|---|---|
GET |
/api/health |
System health check & model readiness | None |
POST |
/api/analyze |
Primary diagnostic endpoint (analyzes fundus scan) | multipart/form-data |
GET |
/api/demo-samples |
Retrieves preloaded benchmark demo scans | None |
GET |
/api/appointments |
Lists scheduled ophthalmology appointments | None |
POST |
/api/appointments |
Creates or manually books a clinical referral | application/json |
GET |
/api/history |
Retrieves historical analysis sessions | Query params |
GET |
/api/history/{id} |
Fetches full report data for an analysis | Path param |
To execute automated backend test suites:
source venv/bin/activate
PYTHONPATH=. pytest backend/tests -vVerified test coverage includes:
- ✅ Retinal circular ROI isolation boundary conditions
- ✅ Multi-scale vessel enhancement and Frangi filter stability
- ✅ Zhang-Suen skeleton convergence and Euler characteristic preservation
- ✅ Clinical Lesion-Gated Reconciliation accuracy on normal vs diseased eyes
- ✅ Appointment auto-booking trigger integrity (guarded for Grade
$\ge 2$ ) - ✅ Database failover between PostgreSQL and SQLite
Distributed under the MIT License. See LICENSE for more information.
Developed for Advanced Clinical Ophthalmology, Telemedicine Screening, and Automated Retinopathy Triage.
OcuPulse Project Repository — 2026