How argirovga/vibration_diagnostics works
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