# georgeyhere/fpga-video-processing architecture

> Architecture diagram of the GitHub repository georgeyhere/fpga-video-processing, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/georgeyhere/fpga-video-processing
- Repository: https://github.com/georgeyhere/fpga-video-processing

## Overview

##### Overall Project Identification
- The project is a hardware design for an FPGA (Artix-7) that implements a video processing pipeline. It captures video via an OV7670 camera, applies filtering (Gaussian lowpass and Sobel edge detection), and outputs data through an HDMI interface.
- The design mixes digital hardware (Verilog RTL) with FPGA IP cores (e.g., clock wizard under the ip directory) and test benches for simulation (under tb).

##### Analyzing the File Structure
- Top-level directories include:
- "ip": Houses the clock management IP core (clk_wiz_0) with various Vivado files, configurations, and board constraints.
- "rtl": Contains all of the hardware modules – camera interfaces, HDMI modules, processing modules (greyscale conversion, Gaussian and Sobel filtering kernels), asynchronous/synchronous FIFOs, memory interfaces, and control logic.
- "tb": Contains simulation test benches to validate each module.
- This grouping shows that the design is modular with each processing stage implemented as separate Verilog modules and IP cores.

##### Extracting Key Components from the README
- The README explains the system is logically divided into:
- Camera Interface: Configuring the OV7670 camera using I²C and capturing pixel data into asynchronous FIFOs.
- Preprocessing: Converting the incoming video data from RGB444 to 8-bit greyscale, using a bit-shift based approximate algorithm (y = 0.299R + 0.587G + 0.114B).
- Kernel Processing: Two main processing pipelines – one for a Gaussian filter and one for a Sobel edge detection. A common kernel control module (ps_kernel_control) organizes line buffers and feeds pixel clusters into the kernel pipelines.
- Memory/Output and Display: Processed data is stored in block RAM (framebuffer) and then accessed by the HDMI transmitter, with conversion from greyscale to a required output format (extension to RGB888 for TMDS encoding). Also includes logic for RGB passthrough mode.

##### Key Components
- External Interfaces:
- OV7670 Camera (including I²C configuration) feeding into the system.
- HDMI Output interface.
- User Input (buttons and switches on the dev board).
- Core Processing Blocks (modules):
- Camera Interface Block: Captures and formats RGB444 video from the OV7670, loading data into an asynchronous FIFO.
- Preprocessing Block: Converts the RGB444 video input to eight-bit greyscale using the provided algorithm.
- Kernel Control & Filtering Blocks:
- Kernel Control Module (ps_kernel_control): Manages line buffers and pixel data extraction.
- Gaussian Filter Module: Implements a Gaussian lowpass filter.
- Sobel Filter Module: Implements edge detection (including thresholding, avoiding square root computations).
- Memory and Display Interface:
- Framebuffer Block: Synthesized block memory used for temporary pixel storage.
- HDMI Transmitter: Converts processed pixel data for display (including RGB444 to TMDS conversion if in passthrough mode, or RGB888 conversion for processed video).
- Support/Utility Components:
- Clock Wizard (under ip): Essential FPGA clock generation and management for timing across modules.
- FIFOs and Memory Interfaces: For asynchronous and synchronous data buffering between stages.

##### Relationships and Data Flow
- From the Camera Interface to Preprocessing (data flow of raw RGB444 video).
- From Preprocessing to Kernel Control (passing greyscale pixel data).
- From Kernel Control to both the Gaussian and Sobel Filtering pipelines (feeding sliding window pixel data).
- From Filtering pipelines to the Framebuffer (synchronized write/read).
- Finally from the Framebuffer to the HDMI Transmitter.
- User interaction feedback (e.g., button inputs selecting video modes and filter thresholds) interfacing with control blocks.

##### Architectural Patterns and Design Principles
- Modular design: Each pipeline stage is treated as an independent module with clearly defined inputs and outputs.
- Pipelining: Streaming data through sequential blocks (camera capture → preprocessing → filtering → output) to maintain throughput and meet real-time video constraints.
- Data buffering: Use of asynchronous/synchronous FIFOs and block RAM to handle timing differences across modules.
- Hardware-specific IP integration: Incorporation of vendor IP (like the clk_wiz_0) to abstract clock management, emphasizing separation of concerns.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Interfaces
    subgraph "External Interfaces"
        OV["OV7670 Camera"]:::interface
        UI["User Input (Buttons & Switches)"]:::interface
    end

    %% Support/Utility Components
    subgraph "Support/Utilities"
        CLK["Clock Wizard"]:::ip
        FIF["FIFO (Async/Sys)"]:::buffering
    end

    %% Video Processing Pipeline
    subgraph "Video Processing Pipeline"
        CI["Camera Interface Block"]:::processing
        PP["Preprocessing (RGB to Greyscale)"]:::processing
        KC["Kernel Control Module"]:::processing
        GF["Gaussian Filter Module"]:::processing
        SF["Sobel Filter Module"]:::processing
        FB["Framebuffer (Memory Interface)"]:::buffering
        HDMI["HDMI Transmitter / Display"]:::display
    end

    %% Data Flow Connections
    OV -->|"video_in"| CI
    CI -->|"raw_data"| FIF
    FIF -->|"buffered_data"| PP
    PP -->|"greyscale"| KC
    KC -->|"pixel_cluster"| GF
    KC -->|"pixel_cluster"| SF
    GF -->|"filtered"| FB
    SF -->|"edge"| FB
    FB -->|"video_out"| HDMI
    UI -->|"controls"| KC

    %% Clock Distribution
    CLK ---|"clock_signal"| CI
    CLK ---|"clock_signal"| PP
    CLK ---|"clock_signal"| KC
    CLK ---|"clock_signal"| HDMI

    %% Click Events
    click CLK "https://github.com/georgeyhere/fpga-video-processing/blob/master/ip/clk_wiz_0/clk_wiz_0.v"
    click CI "https://github.com/georgeyhere/fpga-video-processing/blob/master/rtl/cam_capture.v"
    click CI "https://github.com/georgeyhere/fpga-video-processing/blob/master/rtl/cam_top.v"
    click CI "https://github.com/georgeyhere/fpga-video-processing/blob/master/rtl/cfg_i2c_master.v"
    click PP "https://github.com/georgeyhere/fpga-video-processing/blob/master/rtl/pp_preprocess.v"
    click PP "https://github.com/georgeyhere/fpga-video-processing/blob/master/rtl/pp_greyscale.v"
    click KC "https://github.com/georgeyhere/fpga-video-processing/blob/master/rtl/ps_kernel_control.v"
    click KC "https://github.com/georgeyhere/fpga-video-processing/blob/master/rtl/ps_linebuffer.v"
    click GF "https://github.com/georgeyhere/fpga-video-processing/blob/master/rtl/ps_gaussian.v"
    click GF "https://github.com/georgeyhere/fpga-video-processing/blob/master/rtl/ps_gaussian_top.v"
    click SF "https://github.com/georgeyhere/fpga-video-processing/blob/master/rtl/ps_sobel.v"
    click SF "https://github.com/georgeyhere/fpga-video-processing/blob/master/rtl/ps_sobel_top.v"
    click FB "https://github.com/georgeyhere/fpga-video-processing/blob/master/rtl/mem_bram.v"
    click FB "https://github.com/georgeyhere/fpga-video-processing/blob/master/rtl/mem_interface.v"
    click HDMI "https://github.com/georgeyhere/fpga-video-processing/blob/master/rtl/HDMI_TMDS.v"
    click HDMI "https://github.com/georgeyhere/fpga-video-processing/blob/master/rtl/HDMI_encode.v"
    click HDMI "https://github.com/georgeyhere/fpga-video-processing/blob/master/rtl/HDMI_out.v"
    click HDMI "https://github.com/georgeyhere/fpga-video-processing/blob/master/rtl/HDMI_top.v"
    click FIF "https://github.com/georgeyhere/fpga-video-processing/blob/master/rtl/fifo_async.v"
    click FIF "https://github.com/georgeyhere/fpga-video-processing/blob/master/rtl/fifo_sync.v"

    %% Styles
    classDef interface fill:#f9e79f,stroke:#f39c12,stroke-width:2px;
    classDef processing fill:#aed6f1,stroke:#2471a3,stroke-width:2px;
    classDef buffering fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef display fill:#fad7a0,stroke:#e67e22,stroke-width:2px;
    classDef ip fill:#e8daef,stroke:#8e44ad,stroke-width:2px;
```
