# argirovga/vibration_diagnostics architecture

> Architecture diagram of the GitHub repository argirovga/vibration_diagnostics, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/argirovga/vibration_diagnostics
- Repository: https://github.com/argirovga/vibration_diagnostics

## Overview

##### Project type and purpose
- This is a Python-based desktop/CLI data-processing application with a Qt GUI front end.
- Purpose: ingest high-speed camera and neuromorphic (event-based) video data, apply event-frame filtering and a genetic algorithm to detect and measure vibrations, then present results interactively or via notebooks.

##### File structure
- Top-level orchestration:
- run.py – entry point for CLI/batch preprocessing
- qt_app.py – Qt-based GUI application
- Data directories:
- raw_data/ – unprocessed frames & videos
- preped_data/ – output of preprocessing pipeline
- Processing modules (each a Python package):
- event_frames/ – code to extract event-frames from raw footage
- event_filter/ – filters and metrics (includes genetic_algorithm.py)
- frame_shifting/ – aligns frames, computes shifts, notebooks for demo
- vibration_calculation/ – core vibration-measurement algorithm
- Notebooks (metrics_calculations.ipynb, frame_shifting_and_vibration_calculation.ipynb) for exploratory analysis.

##### README insights
- Three main algorithmic stages:
a. Event-Frame Filtering (data reduction + enhancement)
b. Genetic-Algorithm Optimization (tune detection parameters)
c. Vibration Measurement (final calculation)
- Visualization via Qt GUI and interactive Jupyter notebooks.

a. Main components
1. Data Sources: High-speed camera videos & event-based cameras (raw_data)
2. Preprocessor Modules (Python packages):
– EventFrameGenerator (event_frames/)
– EventFilterGenerator & GeneticAlgorithm (event_filter/)
– FrameShiftingControl (frame_shifting/)
– VibrationCalculationAlgorithm (vibration_calculation/)
3. Data Storage: File-based (preped_data/) for intermediate outputs
4. Orchestration Layer: run.py for CLI pipelines
5. GUI Layer: qt_app.py for user interaction & visualization
6. Exploratory Notebooks: Jupyter for offline analysis
b. Relationships & Data Flow
– Raw Data → EventFrameGenerator → event_frames output →
EventFilterGenerator → filters → prepped frames →
FrameShiftingControl → aligned frames →
VibrationCalculationAlgorithm → vibration metrics →
preped_data & metrics.json
– Orchestration (run.py) calls each module in sequence and writes to preped_data
– Qt GUI (qt_app.py) reads preped_data, triggers modules on user commands, and displays results
– Notebooks read both raw_data and preped_data for deep dives and visualization
c. Architectural Patterns & Principles
– Modular pipeline: each stage isolated in its own package
– Separation of concerns: data ingestion, processing, optimization, and presentation are distinct
– File-based data contracts: modules exchange data via well-defined directory structure
– Extensibility: new filtering algorithms or measurement techniques can be plugged into the pipeline
d. Key Technologies & Libraries
– Python 3.8+
– OpenCV / NumPy / SciPy for image processing
– Genetic algorithm library or custom implementation
– PyQt or PySide for GUI (qt_app.py)
– Jupyter for notebooks

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Sources & Storage
    subgraph "Data Sources & Storage"
        direction TB
        RawData["Raw Data (raw_data/)"]:::data
        PreppedData["Preprocessed Data (preped_data/)"]:::data
    end

    %% Processing Modules
    subgraph "Processing Modules"
        direction TB
        EventFrameGen["EventFrameGenerator"]:::processing
        EventFilterGen["EventFilterGenerator"]:::processing
        GeneticAlg["GeneticAlgorithm"]:::processing
        FrameShifting["FrameShiftingControl"]:::processing
        VibrationCalc["VibrationCalculationAlgorithm"]:::processing
    end

    %% Orchestration & UI
    subgraph "Orchestration & UI"
        direction TB
        CLI["run.py"]:::ui
        GUI["qt_app.py"]:::ui
    end

    %% Exploratory Notebooks
    subgraph "Exploratory Notebooks"
        direction TB
        NotebookMetrics["Metrics Calculations Notebook"]:::notebooks
        NotebookShift["Frame Shifting & Vibration Notebook"]:::notebooks
    end

    %% Data Flow
    RawData -->|ingest raw frames| EventFrameGen
    EventFrameGen -->|generate event frames| EventFilterGen
    EventFilterGen -->|apply filters| GeneticAlg
    GeneticAlg -->|optimized params| FrameShifting
    FrameShifting -->|aligned frames| VibrationCalc
    VibrationCalc -->|compute metrics| PreppedData

    %% Orchestration Paths
    CLI -->|batch pipeline| EventFrameGen
    GUI -->|interactive trigger| EventFrameGen
    GUI -->|reads results| PreppedData

    %% Notebook Paths
    NotebookMetrics -->|reads| RawData
    NotebookMetrics -->|reads| PreppedData
    NotebookShift -->|uses| FrameShifting
    NotebookShift -->|uses| VibrationCalc

    %% Click events
    click RawData "https://github.com/argirovga/vibration_diagnostics/tree/main/raw_data/"
    click PreppedData "https://github.com/argirovga/vibration_diagnostics/tree/main/preped_data/"
    click EventFrameGen "https://github.com/argirovga/vibration_diagnostics/blob/main/event_frames/event_frame_generator.py"
    click EventFilterGen "https://github.com/argirovga/vibration_diagnostics/blob/main/event_filter/event_filter_generator.py"
    click GeneticAlg "https://github.com/argirovga/vibration_diagnostics/blob/main/event_filter/genetic_algorithm.py"
    click FrameShifting "https://github.com/argirovga/vibration_diagnostics/blob/main/frame_shifting/frame_shifting_control_algorithm.py"
    click VibrationCalc "https://github.com/argirovga/vibration_diagnostics/blob/main/vibration_calculation/vibration_calculation_algorithm.py"
    click CLI "https://github.com/argirovga/vibration_diagnostics/blob/main/run.py"
    click GUI "https://github.com/argirovga/vibration_diagnostics/blob/main/qt_app.py"
    click NotebookMetrics "https://github.com/argirovga/vibration_diagnostics/blob/main/event_filter/metrics_calculations.ipynb"
    click NotebookShift "https://github.com/argirovga/vibration_diagnostics/blob/main/frame_shifting_and_vibration_calculation.ipynb"

    %% Styles
    classDef data fill:#blue,stroke:#000,color:#fff
    classDef processing fill:#9f6,stroke:#000,color:#000
    classDef ui fill:#f96,stroke:#000,color:#000
    classDef notebooks fill:#d9f,stroke:#000,color:#000
```
