# ahmed23adel/cv_scene_recognition architecture

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

- Interactive diagram: https://gitdiagram.com/ahmed23adel/cv_scene_recognition
- Repository: https://github.com/ahmed23adel/cv_scene_recognition

## Overview

##### Project Type and Purpose
- This is a research‐style, command‐line Python application for computer‐vision‐based scene recognition.
- It implements two feature‐extraction methods (Tiny Image, Bag of Words with HOG + K-means) and two classifiers (Nearest Neighbor, linear SVM).
- It ingests a labeled dataset (data/train & data/test), runs a complete pipeline (feature extraction → classification → evaluation), and emits a static HTML results page.

##### File Structure Analysis
- Top‐level directories:
- code/ – orchestrators and modules:
◦ main.py: CLI entrypoint and overall pipeline controller
◦ helpers.py: I/O utilities (image loading, normalization, HOG computation)
◦ student.py: user‐implementable feature‐extraction and classification routines
◦ create_results_webpage.py: HTML generator for visualizing results
- data/ – structured dataset: per‐class subdirs under train/ and test/
- results_webpage/ – static output (index.html + thumbnails)
- requirements.txt, virtual environment (venv2/)
- No frontend/backend separation: it’s a single‐process batch pipeline.
- Key config/build files: requirements.txt for dependencies (numpy, scikit‐learn, scikit‐image).

##### README Insights
- Clearly lists three feature extractors and two classifiers.
- Describes a three‐step process: feature extraction → classification → evaluation (confusion matrix + HTML page).
- Illustrates usage via command‐line flags.

1. Dataset Storage
– “data/train” and “data/test” directories
2. Feature Extraction Module
– Tiny Image submodule
– Bag of Words submodule (HOG descriptor + K-means vocabulary builder)
3. Model Training Module
– Nearest Neighbor Trainer
– SVM Trainer (one-vs-all linear SVM)
4. Classification Module
– Applies chosen classifier to test features
5. Evaluation Module
– Confusion matrix builder
6. Results Webpage Generator
– HTML creation (create_results_webpage.py) → outputs results_webpage/index.html
7. Orchestrator (main.py)
– Parses CLI flags, calls student.py implementations and helpers.py utilities

– Dataset → Feature Extraction → Feature Vectors
– Feature Vectors → Model Training → Trained Models
– Test Feature Vectors + Trained Models → Classification → Predictions
– Predictions + Ground Truth → Evaluation → Confusion Matrix
– Confusion Matrix + Thumbnails → Webpage Generator → Static HTML

c. Architectural Patterns & Principles
– Pipeline pattern: sequential processing stages
– Modular separation: extraction, training, classification, evaluation, reporting
– Single‐process, procedural design with clearly decoupled modules

d. Key Technologies & Libraries
– Python 3.x
– NumPy for array ops
– scikit‐image or OpenCV for image I/O & HOG
– scikit‐learn for K-means, SVM, Nearest Neighbors
– Matplotlib or HTML templates for visualization

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Orchestrator"
        O["Orchestrator\n(main.py)"]:::pipeline
    end

    subgraph "Data Storage"
        Train["Training Images"]:::dataStore
        Test["Test Images"]:::dataStore
    end

    subgraph "Utilities"
        Utils["I/O & Utilities\n(helpers.py)"]:::dataStore
    end

    subgraph "Feature Extraction"
        Tiny["Tiny Image"]:::compute
        BOW["Bag of Words"]:::compute
        Vocab["K-means Vocabulary"]:::dataStore
    end

    subgraph "Model Training"
        NN["Nearest Neighbor Trainer"]:::compute
        SVM["Linear SVM Trainer"]:::compute
    end

    subgraph "Classification"
        Classify["Classification Module"]:::compute
    end

    subgraph "Evaluation & Reporting"
        Eval["Confusion Matrix Builder"]:::eval
        WebGen["Results Webpage Generator"]:::eval
        Thumbs["Thumbnails"]:::dataStore
        HTML["Results Webpage"]:::doc
    end

    O --> Utils
    O --> Tiny
    O --> BOW
    O --> NN
    O --> SVM
    O --> Classify
    O --> Eval
    O --> WebGen

    Train --> Tiny
    Train --> BOW
    Test --> Classify
    Utils --> Tiny
    Utils --> BOW
    Utils --> Classify

    BOW --> Vocab

    Tiny --> NN
    BOW --> NN
    Tiny --> SVM
    BOW --> SVM

    NN --> Classify
    SVM --> Classify

    Classify --> Eval
    Eval --> WebGen
    Thumbs --> WebGen
    WebGen --> HTML

    click O "https://github.com/ahmed23adel/cv_scene_recognition/blob/main/code/main.py"
    click Utils "https://github.com/ahmed23adel/cv_scene_recognition/blob/main/code/helpers.py"
    click WebGen "https://github.com/ahmed23adel/cv_scene_recognition/blob/main/code/create_results_webpage.py"
    click Train "https://github.com/ahmed23adel/cv_scene_recognition/tree/main/data/train/"
    click Test "https://github.com/ahmed23adel/cv_scene_recognition/tree/main/data/test/"
    click HTML "https://github.com/ahmed23adel/cv_scene_recognition/blob/main/results_webpage/index.html"
    click Thumbs "https://github.com/ahmed23adel/cv_scene_recognition/tree/main/results_webpage/thumbnails/"
    click Vocab "https://github.com/ahmed23adel/cv_scene_recognition/blob/main/vocab.npy"
    click Req "https://github.com/ahmed23adel/cv_scene_recognition/blob/main/requirements.txt"

    classDef dataStore fill:#ADD8E6,stroke:#000;
    classDef compute fill:#90EE90,stroke:#000;
    classDef eval fill:#FFA500,stroke:#000;
    classDef doc fill:#FFD700,stroke:#000;
    classDef pipeline fill:#E6E6FA,stroke:#000;
```
