# dnxjcui/neuromorphic-screens architecture

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

- Interactive diagram: https://gitdiagram.com/dnxjcui/neuromorphic-screens
- Repository: https://github.com/dnxjcui/neuromorphic-screens

## Overview

##### Project Type and Purpose
- neuromorphic_screens.exe (CLI + ImGui replay)
- neuromorphic_screens_streaming.exe (live GUI, overlay, UDP)
- A Python-based test suite/visualizer lives under src/test_UDP, using a bundled virtual environment.

##### File Structure
- Top Level
- CMakeLists.txt: defines 3 targets (capture/replay exe, streaming exe, benchmark tool)
- benchmark_parallelization.cpp, build_benchmark.bat: OpenMP performance test
- docs/: demo GIFs
- env/: isolated Python venv for UDP tests
- src/: main application code, subdivided into capture/, core/, streaming/, visualization/, test_UDP/
- src/capture: Desktop Duplication API + OpenMP to detect pixel changes
- src/core: command-line parsing, event data structures, file I/O, temporal index, timing
- src/streaming: high-throughput UDP event streamer with adaptive dropping
- src/visualization: multiple GUIs (ImGui event viewer, ImGui streaming viewer, direct overlay)
- src/test_UDP: Python scripts for testing and visualizing UDP streaming

##### README for Additional Insights
- Modes of operation (capture, replay, GUI, overlay, UDP streaming)
- Performance features: ring buffer temporal index, dirty‐region tracking, event deduplication, batch processing
- Technical stack: DirectX 11, OpenMP, ImGui, CMake, Python+PyOpenGL+ImGui (for test_UDP)

1. Screen Capture Module (src/capture)
2. Core Event Engine (src/core)
– Command Line Parser
– EventGenerator & EventStream
– EventFile I/O (AEDAT/CSV/TXT)
– TemporalEventIndex & Deduplication
– Timing & Performance Counters
3. Streaming Engine (src/streaming)
– UDPEventStreamer
4. Visualization Layer
– ImGui Event Viewer (src/visualization/imgui_event_viewer)
– ImGui Streaming Viewer (src/visualization/imgui_streaming_viewer)
– Direct Overlay Viewer (src/visualization/direct_overlay_viewer)
5. Command-line Executables
– main.cpp (capture + replay + GUI)
– main_streaming.cpp (live/overlay/UDP)
6. External/Secondary Components
– File System (for .aedat/.csv/.txt storage)
– Network (UDP socket)
– Python UDP Visualizer (src/test_UDP)
– Third-party libs: DirectX11, ImGui, OpenMP

1. Screen → [Capture Module] → Pixel-change events
2. → [Core Event Engine] → timestamped EventStream →
- → [File I/O] → Disk
- → [Temporal Index + Deduplication] → filtered stream →
– → [ImGui Event Viewer] (on replay)
– → [ImGui Streaming Viewer] (live GUI)
– → [Direct Overlay Viewer] (live overlay)
– → [UDP EventStreamer] → Network
· → [Python UDP Visualizer]

c. Architectural Patterns & Design Principles
- Modular layering: capture, core, streaming, UI
- Single Responsibility: each directory/module has a clear focus
- Lock-free / Mutex-protected data structures for thread safety
- Batch processing & ring‐buffer indexing for O(k) recent‐event access
- Adaptive network backpressure / event dropping

d. Key Technologies & Frameworks
- Desktop Duplication API + DirectX11 for capture & rendering
- OpenMP for parallel pixel processing (benchmark and in capture)
- Dear ImGui for all C++ GUIs
- BSD-style sockets (UDP) for network streaming
- CMake for build orchestration
- Python + PyOpenGL + imgui[glfw] for test_UDP visualizer

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Executables
    E1["neuromorphic_screens.exe\n(src/main.cpp)"]:::exe
    E2["neuromorphic_screens_streaming.exe"]:::exe

    %% Capture Layer
    subgraph "Capture Layer"
        SC["Screen Capture Module"]:::capture
    end

    %% Core Layer
    subgraph "Core Layer"
        CLP["Command Line Parser"]:::core
        ET["Event Data Types"]:::core
        SAP["Streaming App Entry"]:::core
        EFI["Event File I/O"]:::core
        TI["Temporal Index & Deduplication"]:::core
        TPC["Timing & Performance Counters"]:::core
    end

    %% Streaming Layer
    subgraph "Streaming Layer"
        UDP["UDP EventStreamer"]:::streaming
    end

    %% Visualization Layer
    subgraph "Visualization Layer"
        IMB["Common ImGui Base"]:::vis
        IEV["ImGui Event Viewer"]:::vis
        ISV["ImGui Streaming Viewer"]:::vis
        DOV["Direct Overlay Viewer"]:::vis
    end

    %% External
    Disk["Disk (.aedat/.csv/.txt)"]:::external
    Network["Network (UDP)"]:::external
    Python["Python UDP Visualizer"]:::external
    Benchmark["Benchmark Tool"]:::external
    CMake["Build Config\n(CMakeLists.txt)"]:::external

    %% Data Flows
    E1 -->|launch| CLP
    E1 -->|launch| SC
    E2 -->|launch| CLP
    E2 -->|launch| SC

    CLP -->|configures| SAP
    SC -->|pixel events| SAP
    SAP -->|branch to file| EFI
    SAP -->|branch to processing| TI
    SAP -->|timing data| TPC

    EFI -.->|writes| Disk
    TI -->|events| IEV
    TI -->|events| ISV
    TI -->|events| DOV
    TI -->|events| UDP

    UDP -->|stream UDP| Network
    Network -.->|receives| Python

    IMB -->|UI base| IEV
    IMB -->|UI base| ISV
    IMB -->|UI base| DOV

    %% Benchmarks & Build
    Benchmark -.->|uses OpenMP| SC
    CMake --> SC
    CMake --> CLP
    CMake --> SAP
    CMake --> EFI
    CMake --> TI
    CMake --> TPC
    CMake --> UDP
    CMake --> IMB
    CMake --> IEV
    CMake --> ISV
    CMake --> DOV
    CMake --> E1
    CMake --> E2

    %% Click Events
    click SC "https://github.com/dnxjcui/neuromorphic-screens/blob/main/src/capture/screen_capture.cpp"
    click CLP "https://github.com/dnxjcui/neuromorphic-screens/blob/main/src/core/command_line_parser.h"
    click ET "https://github.com/dnxjcui/neuromorphic-screens/blob/main/src/core/event_types.h"
    click EFI "https://github.com/dnxjcui/neuromorphic-screens/blob/main/src/core/event_file_formats.cpp"
    click SAP "https://github.com/dnxjcui/neuromorphic-screens/blob/main/src/core/streaming_app.cpp"
    click TI "https://github.com/dnxjcui/neuromorphic-screens/blob/main/src/core/temporal_index.h"
    click TPC "https://github.com/dnxjcui/neuromorphic-screens/blob/main/src/core/timing.cpp"
    click E1 "https://github.com/dnxjcui/neuromorphic-screens/blob/main/src/main.cpp"
    click UDP "https://github.com/dnxjcui/neuromorphic-screens/blob/main/src/streaming/udp_event_streamer.cpp"
    click IEV "https://github.com/dnxjcui/neuromorphic-screens/blob/main/src/visualization/imgui_event_viewer.cpp"
    click ISV "https://github.com/dnxjcui/neuromorphic-screens/blob/main/src/visualization/imgui_streaming_viewer.cpp"
    click DOV "https://github.com/dnxjcui/neuromorphic-screens/blob/main/src/visualization/direct_overlay_viewer.cpp"
    click IMB "https://github.com/dnxjcui/neuromorphic-screens/blob/main/src/visualization/imgui_viewer_base.cpp"
    click Python "https://github.com/dnxjcui/neuromorphic-screens/blob/main/src/test_UDP/neuromorphic_udp_visualizer.py"
    click Benchmark "https://github.com/dnxjcui/neuromorphic-screens/blob/main/benchmark_parallelization.cpp"
    click CMake "https://github.com/dnxjcui/neuromorphic-screens/blob/main/CMakeLists.txt"

    %% Styles
    classDef capture fill:#e0ffd8,stroke:#2d8f2d,stroke-width:2px
    classDef core fill:#d0e7ff,stroke:#1f5bbf,stroke-width:2px
    classDef streaming fill:#ffe0b2,stroke:#bf661f,stroke-width:2px
    classDef vis fill:#f3d1ff,stroke:#8f2dbf,stroke-width:2px
    classDef exe fill:#ffffff,stroke:#000000,stroke-width:2px,stroke-dasharray: 5 5
    classDef external fill:#ffe5e5,stroke:#bf1f1f,stroke-width:2px,stroke-dasharray: 2 2
```
