# napreth/videosemanticrepresentation architecture

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

- Interactive diagram: https://gitdiagram.com/napreth/videosemanticrepresentation
- Repository: https://github.com/napreth/videosemanticrepresentation

## Overview

##### Project type and purpose
- This is an open-source, command-line Python framework for video semantic feature extraction and segment-level retrieval.
- It pipelines raw or sliced video through grayscale conversion, 3D convolution feature extraction, caching, and Euclidean-distance-based search.

##### File structure
Top-level:
- data/ (raw videos, optional 5s slices, output .npy feature files)
- src/ (main entrypoint + three core modules)
- docs/, report/ (documentation & paper)
- requirements.txt, README.md, LICENSE
src/:
- __main__.py – CLI parsing and high-level workflow
- video.py – read video frames, grayscale, wrap OpenCV → CuPy arrays
- feature.py – define 7 custom 3D convolution kernels, perform GPU (CuPy) convolutions, aggregate means, implement file-based cache
- search.py – slide query features over reference features, compute Euclidean distances, report best matching time spans

##### README insights
- CLI commands for “feature” extraction and for “search” (no subcommand)
- Uses OpenCV, CuPy (cupyx.scipy.ndimage.convolve), NumPy, optional ffmpeg for data prep
- Caching keyed by video hash to avoid recomputation

## Diagram (Mermaid)

```mermaid
flowchart TB
    CLI["CLI / User Interface"]:::cli
    ProjectInit["Project Entry & Initialization"]:::store
    VideoIO["Video I/O & Preprocessor"]:::process
    FeatureEngine["Feature Extraction Engine"]:::process
    CacheStore["Feature Cache"]:::store
    DataStore["Feature Files (.npy)"]:::store
    SearchEngine["Search Engine"]:::process
    FFmpeg["ffmpeg"]:::external
    GPU["GPU/CUDA"]:::external

    subgraph Documentation
        Docs["Documentation"]:::store
        Report["Paper & Report"]:::store
    end

    subgraph Metadata
        Req["requirements.txt"]:::external
        Readme["README.md"]:::external
        License["LICENSE"]:::external
    end

    CLI -->|"start pipeline"| VideoIO
    VideoIO -->|"frames as CuPy arrays"| FeatureEngine
    FeatureEngine -->|"writes .npy"| CacheStore
    CacheStore --> DataStore
    CLI -->|"invoke search"| SearchEngine
    DataStore -->|"loads .npy"| SearchEngine
    SearchEngine -->|"results (time spans)"| CLI

    FFmpeg --- VideoIO
    GPU --- VideoIO
    GPU --- FeatureEngine
    CLI --- ProjectInit

    click CLI "https://github.com/napreth/videosemanticrepresentation/blob/main/src/__main__.py"
    click VideoIO "https://github.com/napreth/videosemanticrepresentation/blob/main/src/video.py"
    click FeatureEngine "https://github.com/napreth/videosemanticrepresentation/blob/main/src/feature.py"
    click CacheStore "https://github.com/napreth/videosemanticrepresentation/tree/main/data/features/"
    click DataStore "https://github.com/napreth/videosemanticrepresentation/blob/main/data/features/*.npy"
    click SearchEngine "https://github.com/napreth/videosemanticrepresentation/blob/main/src/search.py"
    click ProjectInit "https://github.com/napreth/videosemanticrepresentation/blob/main/src/__init__.py"
    click Docs "https://github.com/napreth/videosemanticrepresentation/tree/main/docs/"
    click Report "https://github.com/napreth/videosemanticrepresentation/tree/main/report/"
    click Req "https://github.com/napreth/videosemanticrepresentation/blob/main/requirements.txt"
    click Readme "https://github.com/napreth/videosemanticrepresentation/blob/main/README.md"
    click License "https://github.com/napreth/videosemanticrepresentation/tree/main/LICENSE"

    classDef process fill:#add8e6,stroke:#000,stroke-width:1px
    classDef store fill:#90ee90,stroke:#000,stroke-width:1px
    classDef external fill:#ffa500,stroke:#000,stroke-width:1px
    classDef cli fill:#87ceeb,stroke:#000,stroke-width:1px
```
