EyeFlow

EyeFlow is a Python analysis engine and desktop application for retinal Doppler holography. It consumes HoloDoppler image data plus DopplerView segmentation, runs dependency-aware scientific pipelines, and produces HDF5 results, plots, movies, and reports. Vessel segmentation and AI inference are intentionally outside its scope.

Install and run

EyeFlow requires Python 3.10 or newer.

python -m venv .venv
.\.venv\Scripts\activate
pip install -e .

With uv, run uv sync. GPU dependencies are included in the default install.

Launch the desktop application:

eyeflow

Run the CLI over a .holo file, a text list of .holo files, a folder tree, or a ZIP archive:

eyeflow --data path\to\input.holo
eyeflow-cli --data path\to\folder --output path\to\results

eyeflow opens the GUI when invoked without arguments and uses the CLI when arguments are supplied. eyeflow-cli always uses the CLI. Run eyeflow-cli --help for pipeline-list and ZIP-output options.

For the Windows installer, invoke the installed executable directly (use your installed version):

& "$env:LOCALAPPDATA\Programs\eyeflow-python\v1.24.0\EyeFlow 1.24.0.exe" `
  --data "D:\Data\sample.holo" --output "D:\Results"

See installed CLI usage for help, exit codes, and console behavior.

Text lists accept one .holo path per line, with optional surrounding quotes. Entries can point to unrelated directories or different drives:

"Z:\260618\260618_PES1462281_R.holo"
"Y:\260129\260129_DUJ_R_2.holo"

Relative paths are resolved from the text file's directory. Each run uses its own HD/DV companions and writes its results beside that run by default.

In the GUI, drag and drop multiple .holo files and/or folders. Folders are searched recursively, and overlapping selections are deduplicated. Add files / list opens the standard Windows multi-file dialog. Add folder opens the native folder dialog: double-click folders to browse, or select a folder and confirm it to include all .holo files below it. Both actions add to the current selection, so files and folders from different directories/drives can coexist. Repeat either action to add more inputs; Clear starts over. Selecting a .txt list replaces the current selection, and adding files/folders replaces a previously selected text list.

Folder discovery also works without .holo files. Select a run directory such as sample/, or a parent containing several runs, provided each run directory contains matching sample_HD/ and sample_DV/ subdirectories. Existing sample_EF/ and sample_AE/ folders are optional. This works with Add folder, drag-and-drop, and CLI folder inputs. HD/DV HDF5 files are validated as usual; no placeholder .holo file is created. Mixed marker and folder selections are deduplicated, and results remain under sample/sample_EF/ by default.

Input runs

A .holo file anchors separately generated HD and DV companions. For sample.holo, the standard input locations are:

sample/
  sample_HD/h5/sample_HD_output.h5
  sample_DV/h5/sample_DV.h5

Normal runs require both companions. HD volumes use (frame, y, x) axes. DV provides (y, x) artery and vein masks under /segmentation/Retina/artery_mask and /segmentation/Retina/vein_mask, plus optional labels and optic-disc geometry. Timing and pixel-pitch metadata are also required by calibrated products.

See data contracts for exact paths, fallback names, sidecar configuration, validation, axes, and units.

Velocity estimation

Every velocity run attempts both methods:

• doppler_moments uses HD moment0 and moment2, producing calibrated physical velocity in mm/s under /ProcessingMoments.
• frequency_bands (band ratio) uses exact HD datasets /band_0_3000_9000 (LF) and /band_1_9000_18000 (HF), both (frame, y, x). It converts HF / LF to RMS frequency using the positive finite persisted band_ratio_frequency_scale_hz setting, then applies the same local-background, background-difference, and physical velocity conversion. Outputs use /ProcessingBandRatio; the calibration default is 1 Hz per ratio unit.

Cardiac cycles are detected independently before each estimate, from raw moment-derived RMS frequency for moments and calibrated HF/LF frequency for bands. Each workflow uses its own cycle timing and shared /Segmentation geometry. Selected downstream products are recalculated for each method, and PNGs, videos, EPS files, and PDFs use separate moments/ and bandratio/ folders beneath their artifact-type directories.

Missing inputs, invalid data, or a downstream failure skip only the affected workflow. A run fails if neither workflow completes. The HDF5 root records completed methods and failure reasons; method-specific provenance is attached to each processing group and its datasets. Exact-zero LF values map to ratio zero without an epsilon, and LF quality counts remain diagnostic.

Choose velocity workflows in your JSON configuration:

{
  "velocity_estimation_method": "both"
}

Allowed values are doppler_moments, bandratio, and both (the default, including when the key is absent). The former frequency_bands value remains an alias for bandratio. Only selected workflows and their downstream analyses run. Fresh-install defaults are in default_settings.json; velocity is always physical in mm/s, and legacy dimensionless velocity metadata is rejected.

Both velocity workflows reconstruct their local background with OpenCV Telea, using a fixed 5-pixel radius. Frames are processed independently within bounded 32-frame chunks, directly as float32 frequency images without 8-bit scaling or quantization. HDF5 provenance records the method and radius.

Pipelines and outputs

The GUI and CLI use the same catalog, dependency resolver, and execution service. Visible pipelines select products; hidden core pipelines automatically prepare shared heartbeat, topology, and velocity state. Options such as per-beat signals, segments, profiles, quadrants, and blood-volume-rate families add their own dependencies.

For sample.holo, EyeFlow owns sample/sample_EF/. A new attempt replaces an existing directory before running. The primary result is sample_EF/h5/sample_EF.h5; artifact directories such as png, avi, eps, and pdf are created when needed. The output HDF5 records source files, selected targets, resolved execution order/options, version data, and velocity semantics.

Artifact filenames use the acquisition prefix, for example sample_lumen_size_by_branch_artery.png. Writers preserve subfolders and avoid adding the prefix twice. To rename artifacts in existing result folders, run python scripts/migrate_artifacts.py path\to\results --dry-run to inspect the changes, then omit --dry-run to apply them.

Major result families include continuous and per-beat velocity, heartbeat, topology/segmentation, cross-section profiles, waveform metrics, spatial-gradient lumen metrics, blood-volume-rate products, displacement products, and reports. The executable output-path schema is centralized in src/input_output/schema/eyeflow_output.py.

Development

Run the test suite with:

pip install pytest
python -m pytest

Repository navigation for contributors and coding agents starts at AGENTS.md. Deeper references are:

• architecture and source-of-truth map
• data contracts
• test-to-production map
• pipeline contribution guide
• weighted velocity-profile analysis

The tag-triggered GitHub workflow builds Windows releases from dev; it is not a continuous test workflow.