# tub-rip/event_based_optical_flow architecture

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

- Interactive diagram: https://gitdiagram.com/tub-rip/event_based_optical_flow
- Repository: https://github.com/tub-rip/event_based_optical_flow

## Overview

This repository implements research workflows for event-based optical-flow estimation: load event sequences, optimize motion by contrast maximization, then evaluate and visualize predicted flow. The README also describes depth and ego-motion in the journal work, but the supplied tree and excerpts substantiate an optical-flow implementation. Edges reflect visible calls or SOURCE INDEX references; unsampled variants are included as capabilities, with uncertain runtime wiring omitted.

Main entry points: [`src/solver/base.py`](https://github.com/tub-rip/event_based_optical_flow/blob/main/src/solver/base.py) (Solver Base), [`main.py`](https://github.com/tub-rip/event_based_optical_flow/blob/main/main.py) (Experiment Runner), [`src/warp.py`](https://github.com/tub-rip/event_based_optical_flow/blob/main/src/warp.py) (Event Warping), [`src/solver/patch_contrast_base.py`](https://github.com/tub-rip/event_based_optical_flow/blob/main/src/solver/patch_contrast_base.py) (Patch Contrast)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Evaluation Workflow"]
  node_mvsecdata[("MVSEC Sequences<br/>[mvsec.py]")]
  node_loaderapi["Dataset Loading<br/>[base.py]"]
  node_runner["Experiment Runner<br/>[main.py]"]
  node_evaluation["Flow Evaluation<br/>[base.py]"]
  node_visualization["Flow Visualization<br/>[visualizer.py]"]
end

subgraph group_motion["Motion Estimation"]
  node_solverbase["Solver Base<br/>[base.py]"]
  node_patchbase["Patch Contrast"]
  node_mixedsolver["Mixed Solver"]
  node_pyramidsolver["Pyramid Solver"]
  node_timeaware["Time-Aware Solver"]
  node_dnn["EV-FlowNet<br/>[ev_flownet.py]"]
  node_nnlayers["Neural Layers<br/>[basic_layers.py]"]
  node_autograd["SciPy Autograd<br/>[scipy_minimize.py]"]
  node_torchwrapper["Torch Wrapper<br/>[torch_wrapper.py]"]
  node_basewrapper["Autograd Base<br/>[base_wrapper.py]"]
end

subgraph group_objective["Contrast Objectives"]
  node_costs["Contrast Cost Suite"]
  node_hybridcost["Hybrid Cost<br/>[hybrid.py]"]
end

subgraph group_support["Representations &amp; Utilities"]
  node_warping["Event Warping<br/>[warp.py]"]
  node_iwe["Event Image Builder"]
  node_features["Feature Calculator"]
  node_utils["Flow &amp; Event Utilities"]
  node_types["Flow Types<br/>[flow_patch.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"runs experiment"| node_runner
node_runner -->|"selects dataset"| node_loaderapi
node_runner -->|"loads sequence"| node_mvsecdata
node_mvsecdata -->|"uses utilities"| node_utils
node_runner -->|"optimizes events"| node_solverbase
node_runner -->|"evaluates flow"| node_evaluation
node_runner -->|"configures display"| node_visualization
node_solverbase -->|"sets up objective"| node_costs
node_solverbase -->|"builds event images"| node_iwe
node_solverbase -->|"warps events"| node_warping
node_solverbase -->|"renders results"| node_visualization
node_solverbase -->|"uses optimizer"| node_autograd
node_patchbase -->|"extends solver"| node_solverbase
node_patchbase -->|"warps events"| node_warping
node_patchbase -->|"renders results"| node_visualization
node_mixedsolver -->|"uses patch base"| node_patchbase
node_mixedsolver -->|"uses optimizer"| node_autograd
node_pyramidsolver -->|"uses patch base"| node_patchbase
node_pyramidsolver -->|"uses objective"| node_costs
node_pyramidsolver -->|"warps events"| node_warping
node_pyramidsolver -->|"uses optimizer"| node_autograd
node_timeaware -->|"uses utilities"| node_utils
node_dnn -->|"uses layers"| node_nnlayers
node_autograd -->|"wraps SciPy calls"| node_torchwrapper
node_torchwrapper -->|"extends wrapper"| node_basewrapper
node_costs -->|"offers combined loss"| node_hybridcost
node_warping -->|"uses flow transforms"| node_utils
node_warping -->|"uses feature calculator"| node_features
node_visualization -->|"builds event images"| node_iwe
node_visualization -->|"uses warping"| node_warping

click node_mvsecdata "https://github.com/tub-rip/event_based_optical_flow/blob/main/src/data_loader/mvsec.py"
click node_loaderapi "https://github.com/tub-rip/event_based_optical_flow/blob/main/src/data_loader/base.py"
click node_runner "https://github.com/tub-rip/event_based_optical_flow/blob/main/main.py"
click node_evaluation "https://github.com/tub-rip/event_based_optical_flow/blob/main/src/solver/base.py"
click node_visualization "https://github.com/tub-rip/event_based_optical_flow/blob/main/src/visualizer.py"
click node_solverbase "https://github.com/tub-rip/event_based_optical_flow/blob/main/src/solver/base.py"
click node_patchbase "https://github.com/tub-rip/event_based_optical_flow/blob/main/src/solver/patch_contrast_base.py"
click node_mixedsolver "https://github.com/tub-rip/event_based_optical_flow/blob/main/src/solver/patch_contrast_mixed.py"
click node_pyramidsolver "https://github.com/tub-rip/event_based_optical_flow/blob/main/src/solver/patch_contrast_pyramid.py"
click node_timeaware "https://github.com/tub-rip/event_based_optical_flow/blob/main/src/solver/time_aware_patch_contrast.py"
click node_dnn "https://github.com/tub-rip/event_based_optical_flow/blob/main/src/solver/nnmodels/ev_flownet.py"
click node_nnlayers "https://github.com/tub-rip/event_based_optical_flow/blob/main/src/solver/nnmodels/basic_layers.py"
click node_costs "https://github.com/tub-rip/event_based_optical_flow/tree/main/src/costs"
click node_hybridcost "https://github.com/tub-rip/event_based_optical_flow/blob/main/src/costs/hybrid.py"
click node_autograd "https://github.com/tub-rip/event_based_optical_flow/blob/main/src/solver/scipy_autograd/scipy_minimize.py"
click node_torchwrapper "https://github.com/tub-rip/event_based_optical_flow/blob/main/src/solver/scipy_autograd/torch_wrapper.py"
click node_basewrapper "https://github.com/tub-rip/event_based_optical_flow/blob/main/src/solver/scipy_autograd/base_wrapper.py"
click node_warping "https://github.com/tub-rip/event_based_optical_flow/blob/main/src/warp.py"
click node_iwe "https://github.com/tub-rip/event_based_optical_flow/blob/main/src/event_image_converter.py"
click node_features "https://github.com/tub-rip/event_based_optical_flow/blob/main/src/feature_calculator.py"
click node_utils "https://github.com/tub-rip/event_based_optical_flow/tree/main/src/utils"
click node_types "https://github.com/tub-rip/event_based_optical_flow/blob/main/src/types/flow_patch.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_mvsecdata,node_loaderapi,node_runner,node_evaluation,node_visualization toneBlue
class node_solverbase,node_patchbase,node_mixedsolver,node_pyramidsolver,node_timeaware,node_dnn,node_nnlayers,node_autograd,node_torchwrapper,node_basewrapper toneAmber
class node_costs,node_hybridcost toneMint
class node_warping,node_iwe,node_features,node_utils,node_types toneRose
class node_researcher toneIndigo
```

## Components

### Evaluation Workflow

- [MVSEC Sequences](https://github.com/tub-rip/event_based_optical_flow/blob/main/src/data_loader/mvsec.py): `src/data_loader/mvsec.py`
- [Dataset Loading](https://github.com/tub-rip/event_based_optical_flow/blob/main/src/data_loader/base.py): `src/data_loader/base.py`
- [Experiment Runner](https://github.com/tub-rip/event_based_optical_flow/blob/main/main.py): `main.py`
- [Flow Evaluation](https://github.com/tub-rip/event_based_optical_flow/blob/main/src/solver/base.py): `src/solver/base.py`
- [Flow Visualization](https://github.com/tub-rip/event_based_optical_flow/blob/main/src/visualizer.py): `src/visualizer.py`

### Motion Estimation

- [Solver Base](https://github.com/tub-rip/event_based_optical_flow/blob/main/src/solver/base.py): `src/solver/base.py`
- [Patch Contrast](https://github.com/tub-rip/event_based_optical_flow/blob/main/src/solver/patch_contrast_base.py): `src/solver/patch_contrast_base.py`
- [Mixed Solver](https://github.com/tub-rip/event_based_optical_flow/blob/main/src/solver/patch_contrast_mixed.py): `src/solver/patch_contrast_mixed.py`
- [Pyramid Solver](https://github.com/tub-rip/event_based_optical_flow/blob/main/src/solver/patch_contrast_pyramid.py): `src/solver/patch_contrast_pyramid.py`
- [Time-Aware Solver](https://github.com/tub-rip/event_based_optical_flow/blob/main/src/solver/time_aware_patch_contrast.py): `src/solver/time_aware_patch_contrast.py`
- [EV-FlowNet](https://github.com/tub-rip/event_based_optical_flow/blob/main/src/solver/nnmodels/ev_flownet.py): `src/solver/nnmodels/ev_flownet.py`
- [Neural Layers](https://github.com/tub-rip/event_based_optical_flow/blob/main/src/solver/nnmodels/basic_layers.py): `src/solver/nnmodels/basic_layers.py`
- [SciPy Autograd](https://github.com/tub-rip/event_based_optical_flow/blob/main/src/solver/scipy_autograd/scipy_minimize.py): `src/solver/scipy_autograd/scipy_minimize.py`
- [Torch Wrapper](https://github.com/tub-rip/event_based_optical_flow/blob/main/src/solver/scipy_autograd/torch_wrapper.py): `src/solver/scipy_autograd/torch_wrapper.py`
- [Autograd Base](https://github.com/tub-rip/event_based_optical_flow/blob/main/src/solver/scipy_autograd/base_wrapper.py): `src/solver/scipy_autograd/base_wrapper.py`

### Contrast Objectives

- [Contrast Cost Suite](https://github.com/tub-rip/event_based_optical_flow/tree/main/src/costs): `src/costs`
- [Hybrid Cost](https://github.com/tub-rip/event_based_optical_flow/blob/main/src/costs/hybrid.py): `src/costs/hybrid.py`

### Representations & Utilities

- [Event Warping](https://github.com/tub-rip/event_based_optical_flow/blob/main/src/warp.py): `src/warp.py`
- [Event Image Builder](https://github.com/tub-rip/event_based_optical_flow/blob/main/src/event_image_converter.py): `src/event_image_converter.py`
- [Feature Calculator](https://github.com/tub-rip/event_based_optical_flow/blob/main/src/feature_calculator.py): `src/feature_calculator.py`
- [Flow & Event Utilities](https://github.com/tub-rip/event_based_optical_flow/tree/main/src/utils): `src/utils`
- [Flow Types](https://github.com/tub-rip/event_based_optical_flow/blob/main/src/types/flow_patch.py): `src/types/flow_patch.py`

### Other components

- **Researcher**

## Connections

- Researcher → Experiment Runner: runs experiment (evidence: `README.md`)
- Experiment Runner → Dataset Loading: selects dataset (evidence: `main.py`)
- Experiment Runner → MVSEC Sequences: loads sequence (evidence: `main.py`)
- MVSEC Sequences → Flow & Event Utilities: uses utilities (evidence: `src/data_loader/mvsec.py`)
- Experiment Runner → Solver Base: optimizes events (evidence: `main.py`)
- Experiment Runner → Flow Evaluation: evaluates flow (evidence: `main.py`)
- Experiment Runner → Flow Visualization: configures display (evidence: `main.py`)
- Solver Base → Contrast Cost Suite: sets up objective (evidence: `src/solver/base.py`)
- Solver Base → Event Image Builder: builds event images (evidence: `src/solver/base.py`)
- Solver Base → Event Warping: warps events (evidence: `src/solver/base.py`)
- Solver Base → Flow Visualization: renders results (evidence: `src/solver/base.py`)
- Solver Base → SciPy Autograd: uses optimizer (evidence: `src/solver/base.py`)
- Patch Contrast → Solver Base: extends solver (evidence: `src/solver/patch_contrast_base.py`)
- Patch Contrast → Event Warping: warps events (evidence: `src/solver/patch_contrast_base.py`)
- Patch Contrast → Flow Visualization: renders results (evidence: `src/solver/patch_contrast_base.py`)
- Mixed Solver → Patch Contrast: uses patch base (evidence: `src/solver/patch_contrast_mixed.py`)
- Mixed Solver → SciPy Autograd: uses optimizer (evidence: `src/solver/patch_contrast_mixed.py`)
- Pyramid Solver → Patch Contrast: uses patch base (evidence: `src/solver/patch_contrast_pyramid.py`)
- Pyramid Solver → Contrast Cost Suite: uses objective (evidence: `src/solver/patch_contrast_pyramid.py`)
- Pyramid Solver → Event Warping: warps events (evidence: `src/solver/patch_contrast_pyramid.py`)
- Pyramid Solver → SciPy Autograd: uses optimizer (evidence: `src/solver/patch_contrast_pyramid.py`)
- Time-Aware Solver → Flow & Event Utilities: uses utilities (evidence: `src/solver/time_aware_patch_contrast.py`)
- EV-FlowNet → Neural Layers: uses layers (evidence: `src/solver/nnmodels/ev_flownet.py`)
- SciPy Autograd → Torch Wrapper: wraps SciPy calls (evidence: `src/solver/scipy_autograd/scipy_minimize.py`)
- Torch Wrapper → Autograd Base: extends wrapper (evidence: `src/solver/scipy_autograd/torch_wrapper.py`)
- Contrast Cost Suite → Hybrid Cost: offers combined loss (evidence: `src/costs/__init__.py`)
- Event Warping → Flow & Event Utilities: uses flow transforms (evidence: `src/warp.py`)
- Event Warping → Feature Calculator: uses feature calculator (evidence: `src/warp.py`)
- Flow Visualization → Event Image Builder: builds event images (evidence: `src/visualizer.py`)
- Flow Visualization → Event Warping: uses warping (evidence: `src/visualizer.py`)
