# tayari-baha-eddine/eyetrack-fpga architecture

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

- Interactive diagram: https://gitdiagram.com/tayari-baha-eddine/eyetrack-fpga
- Repository: https://github.com/tayari-baha-eddine/eyetrack-fpga

## Overview

EyeTrack-FPGA is a pupil-localization research prototype: it prepares Swirski eye images as 16×16 inputs, trains and evaluates a Python MLP, quantizes it for fixed-point inference, and exports parameters to a sequential VHDL implementation. The README documents bit-exact comparison with a Python integer reference. The main Python evaluation and quantization calls are visible in excerpts; dataset preparation and RTL wiring are represented only where the README documents them, so some edges are omitted.

Main entry points: [`src/evaluation/evaluate.py`](https://github.com/tayari-baha-eddine/eyetrack-fpga/blob/main/src/evaluation/evaluate.py) (Model evaluation), [`rtl/top/eye_mlp_top.vhd`](https://github.com/tayari-baha-eddine/eyetrack-fpga/blob/main/rtl/top/eye_mlp_top.vhd) (MLP top-level), [`src/quantization/quantized_reference.py`](https://github.com/tayari-baha-eddine/eyetrack-fpga/blob/main/src/quantization/quantized_reference.py) (Integer reference), [`src/models/train.py`](https://github.com/tayari-baha-eddine/eyetrack-fpga/blob/main/src/models/train.py) (MLP training)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_prepare["ROI preprocessing"]
  node_prepared[("16×16 dataset")]
end

subgraph group_python["Python modeling"]
  node_train["MLP training<br/>[train.py]"]
  node_floatmodel["EyeMLP<br/>[mlp.py]"]
  node_metrics["Error metrics<br/>[metrics.py]"]
  node_baseline["Threshold baseline<br/>[baseline.py]"]
  node_evaluate["Model evaluation<br/>[evaluate.py]"]
end

subgraph group_fixed["Fixed-point deployment"]
  node_quantize["INT8 quantization<br/>[quantize.py]"]
  node_qparams[("Quantized parameters<br/>[qparams.npz]")]
  node_reference["Integer reference"]
  node_export["VHDL parameter export"]
  node_vectors["Test vectors<br/>[gen_vectors.py]"]
end

subgraph group_hardware["VHDL inference"]
  node_paramsvhdl["VHDL parameters<br/>[eye_mlp_params.vhd]"]
  node_top["MLP top-level<br/>[eye_mlp_top.vhd]"]
  node_dense["Dense layer<br/>[dense_layer.vhd]"]
  node_package["MLP arithmetic package<br/>[mlp_pkg.vhd]"]
  node_testbench["Inference testbench<br/>[tb_eye_mlp.vhd]"]
end

node_researcher(("Researcher"))
node_swirski[("Swirski images")]

node_researcher -->|"prepares data"| node_prepare
node_swirski -->|"provides images"| node_prepare
node_prepare -->|"produces inputs"| node_prepared
node_prepared -->|"trains on"| node_train
node_train -->|"instantiates"| node_floatmodel
node_train -->|"evaluates epochs"| node_metrics
node_prepared -->|"provides split"| node_evaluate
node_evaluate -->|"runs inference"| node_floatmodel
node_evaluate -->|"fits and predicts"| node_baseline
node_evaluate -->|"runs integer inference"| node_reference
node_evaluate -->|"computes errors"| node_metrics
node_floatmodel -->|"provides weights"| node_quantize
node_prepared -->|"calibrates on train"| node_quantize
node_quantize -->|"writes parameters"| node_qparams
node_qparams -->|"loads parameters"| node_reference
node_qparams -->|"loads parameters"| node_export
node_export -->|"writes constants"| node_paramsvhdl
node_paramsvhdl -->|"supplies weights"| node_top
node_top -->|"computes layers"| node_dense
node_top -.->|"uses arithmetic"| node_package
node_vectors -->|"generates reference outputs"| node_reference
node_reference -->|"compared bit-for-bit"| node_testbench
node_testbench -->|"simulates inference"| node_top

click node_prepare "https://github.com/tayari-baha-eddine/eyetrack-fpga/blob/main/src/data/prepare_dataset_swirski.py"
click node_train "https://github.com/tayari-baha-eddine/eyetrack-fpga/blob/main/src/models/train.py"
click node_floatmodel "https://github.com/tayari-baha-eddine/eyetrack-fpga/blob/main/src/models/mlp.py"
click node_metrics "https://github.com/tayari-baha-eddine/eyetrack-fpga/blob/main/src/evaluation/metrics.py"
click node_baseline "https://github.com/tayari-baha-eddine/eyetrack-fpga/blob/main/src/evaluation/baseline.py"
click node_evaluate "https://github.com/tayari-baha-eddine/eyetrack-fpga/blob/main/src/evaluation/evaluate.py"
click node_quantize "https://github.com/tayari-baha-eddine/eyetrack-fpga/blob/main/src/quantization/quantize.py"
click node_qparams "https://github.com/tayari-baha-eddine/eyetrack-fpga/blob/main/artifacts/qparams.npz"
click node_reference "https://github.com/tayari-baha-eddine/eyetrack-fpga/blob/main/src/quantization/quantized_reference.py"
click node_export "https://github.com/tayari-baha-eddine/eyetrack-fpga/blob/main/src/quantization/export_vhdl_params.py"
click node_paramsvhdl "https://github.com/tayari-baha-eddine/eyetrack-fpga/blob/main/rtl/top/eye_mlp_params.vhd"
click node_top "https://github.com/tayari-baha-eddine/eyetrack-fpga/blob/main/rtl/top/eye_mlp_top.vhd"
click node_dense "https://github.com/tayari-baha-eddine/eyetrack-fpga/blob/main/rtl/layers/dense_layer.vhd"
click node_package "https://github.com/tayari-baha-eddine/eyetrack-fpga/blob/main/rtl/units/mlp_pkg.vhd"
click node_testbench "https://github.com/tayari-baha-eddine/eyetrack-fpga/blob/main/rtl/tb/tb_eye_mlp.vhd"
click node_vectors "https://github.com/tayari-baha-eddine/eyetrack-fpga/blob/main/src/quantization/gen_vectors.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_prepare,node_prepared toneBlue
class node_train,node_floatmodel,node_metrics,node_baseline,node_evaluate,node_swirski toneAmber
class node_quantize,node_qparams,node_reference,node_export,node_vectors toneMint
class node_paramsvhdl,node_top,node_dense,node_package,node_testbench toneRose
class node_researcher toneIndigo
```

## Components

### Data preparation

- [ROI preprocessing](https://github.com/tayari-baha-eddine/eyetrack-fpga/blob/main/src/data/prepare_dataset_swirski.py): `src/data/prepare_dataset_swirski.py`
- **16×16 dataset**

### Python modeling

- [MLP training](https://github.com/tayari-baha-eddine/eyetrack-fpga/blob/main/src/models/train.py): `src/models/train.py`
- [EyeMLP](https://github.com/tayari-baha-eddine/eyetrack-fpga/blob/main/src/models/mlp.py): `src/models/mlp.py`
- [Error metrics](https://github.com/tayari-baha-eddine/eyetrack-fpga/blob/main/src/evaluation/metrics.py): `src/evaluation/metrics.py`
- [Threshold baseline](https://github.com/tayari-baha-eddine/eyetrack-fpga/blob/main/src/evaluation/baseline.py): `src/evaluation/baseline.py`
- [Model evaluation](https://github.com/tayari-baha-eddine/eyetrack-fpga/blob/main/src/evaluation/evaluate.py): `src/evaluation/evaluate.py`

### Fixed-point deployment

- [INT8 quantization](https://github.com/tayari-baha-eddine/eyetrack-fpga/blob/main/src/quantization/quantize.py): `src/quantization/quantize.py`
- [Quantized parameters](https://github.com/tayari-baha-eddine/eyetrack-fpga/blob/main/artifacts/qparams.npz): `artifacts/qparams.npz`
- [Integer reference](https://github.com/tayari-baha-eddine/eyetrack-fpga/blob/main/src/quantization/quantized_reference.py): `src/quantization/quantized_reference.py`
- [VHDL parameter export](https://github.com/tayari-baha-eddine/eyetrack-fpga/blob/main/src/quantization/export_vhdl_params.py): `src/quantization/export_vhdl_params.py`
- [Test vectors](https://github.com/tayari-baha-eddine/eyetrack-fpga/blob/main/src/quantization/gen_vectors.py): `src/quantization/gen_vectors.py`

### VHDL inference

- [VHDL parameters](https://github.com/tayari-baha-eddine/eyetrack-fpga/blob/main/rtl/top/eye_mlp_params.vhd): `rtl/top/eye_mlp_params.vhd`
- [MLP top-level](https://github.com/tayari-baha-eddine/eyetrack-fpga/blob/main/rtl/top/eye_mlp_top.vhd): `rtl/top/eye_mlp_top.vhd`
- [Dense layer](https://github.com/tayari-baha-eddine/eyetrack-fpga/blob/main/rtl/layers/dense_layer.vhd): `rtl/layers/dense_layer.vhd`
- [MLP arithmetic package](https://github.com/tayari-baha-eddine/eyetrack-fpga/blob/main/rtl/units/mlp_pkg.vhd): `rtl/units/mlp_pkg.vhd`
- [Inference testbench](https://github.com/tayari-baha-eddine/eyetrack-fpga/blob/main/rtl/tb/tb_eye_mlp.vhd): `rtl/tb/tb_eye_mlp.vhd`

### Other components

- **Researcher**
- **Swirski images**

## Connections

- Researcher → ROI preprocessing: prepares data (evidence: `README.md`)
- Swirski images → ROI preprocessing: provides images (evidence: `README.md`)
- ROI preprocessing → 16×16 dataset: produces inputs (evidence: `README.md`)
- 16×16 dataset → MLP training: trains on (evidence: `README.md`)
- MLP training → EyeMLP: instantiates (evidence: `src/models/train.py`)
- MLP training → Error metrics: evaluates epochs (evidence: `src/models/train.py`)
- 16×16 dataset → Model evaluation: provides split (evidence: `src/evaluation/evaluate.py`)
- Model evaluation → EyeMLP: runs inference (evidence: `src/evaluation/evaluate.py`)
- Model evaluation → Threshold baseline: fits and predicts (evidence: `src/evaluation/evaluate.py`)
- Model evaluation → Integer reference: runs integer inference (evidence: `src/evaluation/evaluate.py`)
- Model evaluation → Error metrics: computes errors (evidence: `src/evaluation/evaluate.py`)
- EyeMLP → INT8 quantization: provides weights (evidence: `src/quantization/quantize.py`)
- 16×16 dataset → INT8 quantization: calibrates on train (evidence: `src/quantization/quantize.py`)
- INT8 quantization → Quantized parameters: writes parameters (evidence: `src/quantization/quantize.py`)
- Quantized parameters → Integer reference: loads parameters (evidence: `src/quantization/quantized_reference.py`)
- Quantized parameters → VHDL parameter export: loads parameters (evidence: `src/quantization/export_vhdl_params.py`)
- VHDL parameter export → VHDL parameters: writes constants (evidence: `src/quantization/export_vhdl_params.py`)
- VHDL parameters → MLP top-level: supplies weights (evidence: `README.md`)
- MLP top-level → Dense layer: computes layers (evidence: `README.md`)
- MLP top-level → MLP arithmetic package: uses arithmetic
- Test vectors → Integer reference: generates reference outputs (evidence: `src/quantization/gen_vectors.py`)
- Integer reference → Inference testbench: compared bit-for-bit (evidence: `README.md`)
- Inference testbench → MLP top-level: simulates inference (evidence: `README.md`)