# thenukadharmaseelan/eyebridge architecture

> Architecture diagram of the GitHub repository thenukadharmaseelan/eyebridge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thenukadharmaseelan/eyebridge
- Repository: https://github.com/thenukadharmaseelan/eyebridge

## Overview

EyeBridge is a batch and Python-API tool for registering retinal FAF images onto IR images. Its main workflow loads image pairs and vessel masks, estimates a transform from a field-of-view scale seed and LoFTR/RANSAC matching, optionally refines it with dense flow, and returns metrics and diagnostic outputs. Landmark-based fallback and landmark evaluation are additional capabilities. The graph follows the README and indexed references; unsampled implementation details are not inferred beyond those references.

Main entry points: [`src/pipeline.py`](https://github.com/thenukadharmaseelan/eyebridge/blob/main/src/pipeline.py) (Registration API), [`src/cli.py`](https://github.com/thenukadharmaseelan/eyebridge/blob/main/src/cli.py) (Batch CLI), [`src/registration.py`](https://github.com/thenukadharmaseelan/eyebridge/blob/main/src/registration.py) (FOV seed and matching), [`src/matching.py`](https://github.com/thenukadharmaseelan/eyebridge/blob/main/src/matching.py) (LoFTR transform fit)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Inputs and interface"]
  node_pair_csv["Pair CSV"]
  node_cli["Batch CLI<br/>[cli.py]"]
  node_image_io["Image and mask loading<br/>[io.py]"]
end

subgraph group_registration["Registration"]
  node_pipeline["Registration API<br/>[pipeline.py]"]
  node_prep["Vessel preprocessing<br/>[preprocessing.py]"]
  node_scale_match["FOV seed and matching<br/>[registration.py]"]
  node_loftr_fit["LoFTR transform fit<br/>[matching.py]"]
  node_loftr_model["LoFTR model loader<br/>[loftr.py]"]
  node_denseflow["Dense-flow refinement<br/>[registration.py]"]
  node_landmarks["Landmark fallback<br/>[landmarks.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_quality_metrics["Image and vessel metrics<br/>[metrics.py]"]
  node_landmark_metrics["Landmark evaluation<br/>[landmarks.py]"]
end

subgraph group_outputs["Results and diagnostics"]
  node_result_csv["Batch result tables<br/>[cli.py]"]
  node_diagnostics["Diagnostic visualizations<br/>[visualization.py]"]
end

node_user(("Research user"))
node_output_dir["Output directory"]

node_user -->|"runs batch"| node_cli
node_user -->|"calls API"| node_pipeline
node_pair_csv -->|"supplies pairs"| node_cli
node_cli -->|"loads inputs"| node_image_io
node_cli -->|"registers pairs"| node_pipeline
node_pipeline -->|"loads images"| node_image_io
node_pipeline -->|"estimates transform"| node_scale_match
node_scale_match -->|"fits matches"| node_loftr_fit
node_loftr_fit -->|"runs matcher"| node_loftr_model
node_scale_match -->|"uses vessel helpers"| node_prep
node_pipeline -->|"refines transform"| node_denseflow
node_pipeline -->|"uses fallback"| node_landmarks
node_pipeline -->|"assembles metrics"| node_quality_metrics
node_cli -->|"evaluates landmarks"| node_landmark_metrics
node_pipeline -->|"creates diagnostics"| node_diagnostics
node_cli -->|"writes summaries"| node_result_csv
node_result_csv -->|"writes files"| node_output_dir
node_diagnostics -->|"saves images"| node_output_dir

click node_cli "https://github.com/thenukadharmaseelan/eyebridge/blob/main/src/cli.py"
click node_image_io "https://github.com/thenukadharmaseelan/eyebridge/blob/main/src/io.py"
click node_pipeline "https://github.com/thenukadharmaseelan/eyebridge/blob/main/src/pipeline.py"
click node_prep "https://github.com/thenukadharmaseelan/eyebridge/blob/main/src/preprocessing.py"
click node_scale_match "https://github.com/thenukadharmaseelan/eyebridge/blob/main/src/registration.py"
click node_loftr_fit "https://github.com/thenukadharmaseelan/eyebridge/blob/main/src/matching.py"
click node_loftr_model "https://github.com/thenukadharmaseelan/eyebridge/blob/main/src/models/loftr.py"
click node_denseflow "https://github.com/thenukadharmaseelan/eyebridge/blob/main/src/registration.py"
click node_landmarks "https://github.com/thenukadharmaseelan/eyebridge/blob/main/src/landmarks.py"
click node_quality_metrics "https://github.com/thenukadharmaseelan/eyebridge/blob/main/src/metrics.py"
click node_landmark_metrics "https://github.com/thenukadharmaseelan/eyebridge/blob/main/src/landmarks.py"
click node_result_csv "https://github.com/thenukadharmaseelan/eyebridge/blob/main/src/cli.py"
click node_diagnostics "https://github.com/thenukadharmaseelan/eyebridge/blob/main/src/visualization.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_pair_csv,node_cli,node_image_io,node_user toneBlue
class node_pipeline,node_prep,node_scale_match,node_loftr_fit,node_loftr_model,node_denseflow,node_landmarks toneAmber
class node_quality_metrics,node_landmark_metrics toneMint
class node_result_csv,node_diagnostics toneRose
class node_output_dir toneIndigo
```

## Components

### Inputs and interface

- **Pair CSV**
- [Batch CLI](https://github.com/thenukadharmaseelan/eyebridge/blob/main/src/cli.py): `src/cli.py`
- [Image and mask loading](https://github.com/thenukadharmaseelan/eyebridge/blob/main/src/io.py): `src/io.py`

### Registration

- [Registration API](https://github.com/thenukadharmaseelan/eyebridge/blob/main/src/pipeline.py): `src/pipeline.py`
- [Vessel preprocessing](https://github.com/thenukadharmaseelan/eyebridge/blob/main/src/preprocessing.py): `src/preprocessing.py`
- [FOV seed and matching](https://github.com/thenukadharmaseelan/eyebridge/blob/main/src/registration.py): `src/registration.py`
- [LoFTR transform fit](https://github.com/thenukadharmaseelan/eyebridge/blob/main/src/matching.py): `src/matching.py`
- [LoFTR model loader](https://github.com/thenukadharmaseelan/eyebridge/blob/main/src/models/loftr.py): `src/models/loftr.py`
- [Dense-flow refinement](https://github.com/thenukadharmaseelan/eyebridge/blob/main/src/registration.py): `src/registration.py`
- [Landmark fallback](https://github.com/thenukadharmaseelan/eyebridge/blob/main/src/landmarks.py): `src/landmarks.py`

### Evaluation

- [Image and vessel metrics](https://github.com/thenukadharmaseelan/eyebridge/blob/main/src/metrics.py): `src/metrics.py`
- [Landmark evaluation](https://github.com/thenukadharmaseelan/eyebridge/blob/main/src/landmarks.py): `src/landmarks.py`

### Results and diagnostics

- [Batch result tables](https://github.com/thenukadharmaseelan/eyebridge/blob/main/src/cli.py): `src/cli.py`
- [Diagnostic visualizations](https://github.com/thenukadharmaseelan/eyebridge/blob/main/src/visualization.py): `src/visualization.py`

### Other components

- **Research user**
- **Output directory**

## Connections

- Research user → Batch CLI: runs batch (evidence: `README.md`)
- Research user → Registration API: calls API (evidence: `README.md`)
- Pair CSV → Batch CLI: supplies pairs (evidence: `README.md`)
- Batch CLI → Image and mask loading: loads inputs (evidence: `src/cli.py`)
- Batch CLI → Registration API: registers pairs (evidence: `src/cli.py`)
- Registration API → Image and mask loading: loads images (evidence: `src/pipeline.py`)
- Registration API → FOV seed and matching: estimates transform (evidence: `src/pipeline.py`)
- FOV seed and matching → LoFTR transform fit: fits matches (evidence: `src/registration.py`)
- LoFTR transform fit → LoFTR model loader: runs matcher (evidence: `src/matching.py`)
- FOV seed and matching → Vessel preprocessing: uses vessel helpers (evidence: `src/registration.py`)
- Registration API → Dense-flow refinement: refines transform (evidence: `README.md`)
- Registration API → Landmark fallback: uses fallback (evidence: `README.md`)
- Registration API → Image and vessel metrics: assembles metrics (evidence: `src/pipeline.py`)
- Batch CLI → Landmark evaluation: evaluates landmarks (evidence: `README.md`)
- Registration API → Diagnostic visualizations: creates diagnostics (evidence: `src/pipeline.py`)
- Batch CLI → Batch result tables: writes summaries (evidence: `README.md`)
- Batch result tables → Output directory: writes files (evidence: `README.md`)
- Diagnostic visualizations → Output directory: saves images (evidence: `README.md`)
