# robotic-vision-lab/edge-informed-contrast-maximization architecture

> Architecture diagram of the GitHub repository robotic-vision-lab/edge-informed-contrast-maximization, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/robotic-vision-lab/edge-informed-contrast-maximization
- Repository: https://github.com/robotic-vision-lab/edge-informed-contrast-maximization

## Overview

EINCM is a research implementation for edge-informed contrast maximization on event-camera data, producing per-pixel motion estimates and optical-flow evaluations. The principal workflow is to load a dataset sample, optimize its motion field across pyramid levels using contrast, edge-correlation, and regularization terms, then evaluate and visualize results. The README documents DSEC, ECD, and MVSEC support and DSEC submission conversion; these are represented even where their implementation was not sampled. Wiring details for unsampled experiment stages are limited to documented capabilities and visible calls.

Main entry points: [`src/experiments/e00/exp_mgr.py`](https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/blob/main/src/experiments/e00/exp_mgr.py) (Experiment manager), [`src/eincm/losses.py`](https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/blob/main/src/eincm/losses.py) (Optimization losses), [`src/dataloaders/mvsec_loader.py`](https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/blob/main/src/dataloaders/mvsec_loader.py) (MVSEC loader), [`src/dsec_npz_to_png.py`](https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/blob/main/src/dsec_npz_to_png.py) (DSEC PNG conversion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experiment["Experiment orchestration"]
  node_entry["Experiment entry<br/>[__main__.py]"]
  node_manager["Experiment manager<br/>[exp_mgr.py]"]
  node_configs["Experiment configuration"]
end

subgraph group_data["Event data"]
  node_dsec_loader["DSEC loader<br/>[dsec_loader.py]"]
  node_ecd_loader["ECD loader<br/>[ecd_loader.py]"]
  node_mvsec_loader["MVSEC loader<br/>[mvsec_loader.py]"]
  node_mvsec_reader["MVSEC reader<br/>[mvsec_reader.py]"]
  node_hdf5_reader["HDF5 reader"]
  node_numpy_reader["NumPy reader"]
  node_edge_extraction["Edge extraction"]
end

subgraph group_optimization["Motion optimization"]
  node_solver["Pyramid solver<br/>[solver.py]"]
  node_losses["Optimization losses<br/>[losses.py]"]
  node_warpers["Event warping<br/>[event_warpers.py]"]
  node_objectives["Contrast and correlation"]
  node_regularizers["Field regularizers<br/>[regularizers.py]"]
  node_callbacks["Optimization callbacks<br/>[callbacks.py]"]
end

subgraph group_evaluation["Evaluation outputs"]
  node_theta_eval["Theta evaluation<br/>[theta_eval.py]"]
  node_flow_eval["Flow metrics<br/>[flow_eval.py]"]
  node_plotter["Experiment plots<br/>[plotters.py]"]
  node_results["Experiment results"]
  node_converter["DSEC PNG conversion<br/>[dsec_npz_to_png.py]"]
end

node_researcher(("Researcher"))
node_event_datasets[("Event datasets")]
node_submission["DSEC submission files"]

node_researcher -->|"runs experiment"| node_entry
node_configs -->|"configures run"| node_entry
node_entry -->|"starts run"| node_manager
node_manager -->|"selects dataset"| node_dsec_loader
node_manager -->|"selects dataset"| node_ecd_loader
node_manager -->|"selects dataset"| node_mvsec_loader
node_event_datasets -->|"provides samples"| node_dsec_loader
node_event_datasets -->|"provides samples"| node_ecd_loader
node_event_datasets -->|"provides samples"| node_mvsec_loader
node_mvsec_loader -->|"reads data"| node_mvsec_reader
node_mvsec_reader -->|"reads HDF5"| node_hdf5_reader
node_mvsec_reader -->|"reads NumPy"| node_numpy_reader
node_dsec_loader -->|"yields samples"| node_manager
node_ecd_loader -->|"yields samples"| node_manager
node_mvsec_loader -->|"yields samples"| node_manager
node_manager -->|"prepares edges"| node_edge_extraction
node_manager -->|"optimizes sample"| node_solver
node_solver -->|"minimizes loss"| node_losses
node_losses -->|"warps events"| node_warpers
node_losses -->|"computes objectives"| node_objectives
node_losses -->|"computes penalties"| node_regularizers
node_solver -->|"reports iterations"| node_callbacks
node_manager -->|"evaluates estimates"| node_theta_eval
node_theta_eval -->|"computes metrics"| node_losses
node_theta_eval -->|"scores flow"| node_flow_eval
node_manager -->|"plots results"| node_plotter
node_manager -->|"stores results"| node_results
node_researcher -->|"converts results"| node_converter
node_results -->|"provides estimates"| node_converter
node_event_datasets -->|"provides timestamps"| node_converter
node_converter -->|"writes PNG flow"| node_submission

click node_entry "https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/blob/main/src/experiments/e00/__main__.py"
click node_manager "https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/blob/main/src/experiments/e00/exp_mgr.py"
click node_configs "https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/tree/main/src/experiments/e00/configs"
click node_dsec_loader "https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/blob/main/src/dataloaders/dsec_loader.py"
click node_ecd_loader "https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/blob/main/src/dataloaders/ecd_loader.py"
click node_mvsec_loader "https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/blob/main/src/dataloaders/mvsec_loader.py"
click node_mvsec_reader "https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/blob/main/src/dataloaders/mvsec_utils/mvsec_reader.py"
click node_hdf5_reader "https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/blob/main/src/dataloaders/reader_utils/hdf5_file_reader.py"
click node_numpy_reader "https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/blob/main/src/dataloaders/reader_utils/numpy_file_reader.py"
click node_edge_extraction "https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/tree/main/src/experiments/e00"
click node_solver "https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/blob/main/src/eincm/solver.py"
click node_losses "https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/blob/main/src/eincm/losses.py"
click node_warpers "https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/blob/main/src/eincm/event_warpers.py"
click node_objectives "https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/tree/main/src/eincm/objectives"
click node_regularizers "https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/blob/main/src/eincm/regularizers.py"
click node_callbacks "https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/blob/main/src/eincm/callbacks.py"
click node_theta_eval "https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/blob/main/src/evaluations/theta_eval.py"
click node_flow_eval "https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/blob/main/src/evaluations/flow_eval.py"
click node_plotter "https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/blob/main/src/experiments/e00/plotters.py"
click node_results "https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/tree/main/src/outputs"
click node_converter "https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/blob/main/src/dsec_npz_to_png.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_entry,node_manager,node_configs toneBlue
class node_dsec_loader,node_ecd_loader,node_mvsec_loader,node_mvsec_reader,node_hdf5_reader,node_numpy_reader,node_edge_extraction,node_event_datasets toneAmber
class node_solver,node_losses,node_warpers,node_objectives,node_regularizers,node_callbacks toneMint
class node_theta_eval,node_flow_eval,node_plotter,node_results,node_converter toneRose
class node_researcher,node_submission toneIndigo
```

## Components

### Experiment orchestration

- [Experiment entry](https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/blob/main/src/experiments/e00/__main__.py): `src/experiments/e00/__main__.py`
- [Experiment manager](https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/blob/main/src/experiments/e00/exp_mgr.py): `src/experiments/e00/exp_mgr.py`
- [Experiment configuration](https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/tree/main/src/experiments/e00/configs): `src/experiments/e00/configs`

### Event data

- [DSEC loader](https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/blob/main/src/dataloaders/dsec_loader.py): `src/dataloaders/dsec_loader.py`
- [ECD loader](https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/blob/main/src/dataloaders/ecd_loader.py): `src/dataloaders/ecd_loader.py`
- [MVSEC loader](https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/blob/main/src/dataloaders/mvsec_loader.py): `src/dataloaders/mvsec_loader.py`
- [MVSEC reader](https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/blob/main/src/dataloaders/mvsec_utils/mvsec_reader.py): `src/dataloaders/mvsec_utils/mvsec_reader.py`
- [HDF5 reader](https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/blob/main/src/dataloaders/reader_utils/hdf5_file_reader.py): `src/dataloaders/reader_utils/hdf5_file_reader.py`
- [NumPy reader](https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/blob/main/src/dataloaders/reader_utils/numpy_file_reader.py): `src/dataloaders/reader_utils/numpy_file_reader.py`
- [Edge extraction](https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/tree/main/src/experiments/e00): `src/experiments/e00`

### Motion optimization

- [Pyramid solver](https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/blob/main/src/eincm/solver.py): `src/eincm/solver.py`
- [Optimization losses](https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/blob/main/src/eincm/losses.py): `src/eincm/losses.py`
- [Event warping](https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/blob/main/src/eincm/event_warpers.py): `src/eincm/event_warpers.py`
- [Contrast and correlation](https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/tree/main/src/eincm/objectives): `src/eincm/objectives`
- [Field regularizers](https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/blob/main/src/eincm/regularizers.py): `src/eincm/regularizers.py`
- [Optimization callbacks](https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/blob/main/src/eincm/callbacks.py): `src/eincm/callbacks.py`

### Evaluation outputs

- [Theta evaluation](https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/blob/main/src/evaluations/theta_eval.py): `src/evaluations/theta_eval.py`
- [Flow metrics](https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/blob/main/src/evaluations/flow_eval.py): `src/evaluations/flow_eval.py`
- [Experiment plots](https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/blob/main/src/experiments/e00/plotters.py): `src/experiments/e00/plotters.py`
- [Experiment results](https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/tree/main/src/outputs): `src/outputs`
- [DSEC PNG conversion](https://github.com/robotic-vision-lab/edge-informed-contrast-maximization/blob/main/src/dsec_npz_to_png.py): `src/dsec_npz_to_png.py`

### Other components

- **Researcher**
- **Event datasets**
- **DSEC submission files**

## Connections

- Researcher → Experiment entry: runs experiment
- Experiment configuration → Experiment entry: configures run
- Experiment entry → Experiment manager: starts run
- Experiment manager → DSEC loader: selects dataset
- Experiment manager → ECD loader: selects dataset
- Experiment manager → MVSEC loader: selects dataset
- Event datasets → DSEC loader: provides samples
- Event datasets → ECD loader: provides samples
- Event datasets → MVSEC loader: provides samples
- MVSEC loader → MVSEC reader: reads data
- MVSEC reader → HDF5 reader: reads HDF5
- MVSEC reader → NumPy reader: reads NumPy
- DSEC loader → Experiment manager: yields samples
- ECD loader → Experiment manager: yields samples
- MVSEC loader → Experiment manager: yields samples
- Experiment manager → Edge extraction: prepares edges
- Experiment manager → Pyramid solver: optimizes sample
- Pyramid solver → Optimization losses: minimizes loss
- Optimization losses → Event warping: warps events
- Optimization losses → Contrast and correlation: computes objectives
- Optimization losses → Field regularizers: computes penalties
- Pyramid solver → Optimization callbacks: reports iterations
- Experiment manager → Theta evaluation: evaluates estimates
- Theta evaluation → Optimization losses: computes metrics
- Theta evaluation → Flow metrics: scores flow
- Experiment manager → Experiment plots: plots results
- Experiment manager → Experiment results: stores results
- Researcher → DSEC PNG conversion: converts results
- Experiment results → DSEC PNG conversion: provides estimates
- Event datasets → DSEC PNG conversion: provides timestamps
- DSEC PNG conversion → DSEC submission files: writes PNG flow