# harry-kit/image-classification-on-small-datasets-in-pytorch architecture

> Architecture diagram of the GitHub repository harry-kit/image-classification-on-small-datasets-in-pytorch, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harry-kit/image-classification-on-small-datasets-in-pytorch
- Repository: https://github.com/harry-kit/image-classification-on-small-datasets-in-pytorch

## Overview

##### Project type and purpose
- This is a PyTorch-based research toolkit (a CLI application) for fine-tuning and feature-extracting a variety of pretrained CNN and Vision Transformer models on small image datasets.
- It provides utilities to split a dataset, train models, evaluate metrics, and generate Grad-CAM visualizations (static and video).

##### File structure
- Top-level scripts (CLI entry points):
- split_dataset.py
- train.py
- test.py
- grad_cam_results.py
- grad_cam_video_results.py
- Core modules:
- config.py            – experiment hyperparameters (paths, image size, batch size, etc.)
- data_loader.py      – DataLoader wrapper for train/val image directories
- cnn_models.py       – factory for initializing torchvision models with custom heads
- metrics.py          – functions to compute accuracy, loss curves, confusion matrices, classification reports
- utils.py            – plotting utilities, checkpoint save/load, seeding, device management
- Folders for I/O:
- samples1/           – example input images and Grad-CAM video/gif samples
- examples/           – output folders per model, containing accuracy/loss plots, confusion matrices, Grad-CAM images

##### README for additional insights
- The README describes the four CLI steps:
a. `split_dataset.py` – organize raw images into train/val subfolders
b. `train.py` – choose a model, fine-tune or feature-extract, save `.pth` checkpoint and metric plots in `examples/[model]-gradresults/`
c. `grad_cam_results.py` & `grad_cam_video_results.py` – load checkpoint + input image, run Grad-CAM, write visualizations back to an examples folder
d. `test.py` – likely loads a checkpoint and runs on a test set (not detailed but implied)
- The architecture is entirely local; no external services, databases, or servers are involved.

##### Main components
a. CLI Layer
- Scripts: split_dataset, train, test, grad_cam_results, grad_cam_video_results

b. Core Library Layer
- Config Module
- DataLoader Module
- Model Factory Module
- Metrics Module
- Utils Module

c. External Library Layer
- PyTorch / torchvision.models
- OpenCV or PIL (for image I/O, plotting)
- Matplotlib or Seaborn (for plots)

d. Data Storage
- Raw Dataset Directory (input)
- Organized Train/Val directories (after split)
- Checkpoints (`.pth`)
- Plots & Grad-CAM images/videos under `examples/` and `samples1/`

##### Relationships and data flows
- split_dataset.py reads Raw Dataset → writes Train/Val folders
- train.py
- imports config, data_loader → loads images → loads a chosen CNN model via cnn_models.initialize_model → trains → writes checkpoint + metrics to disk
- test.py
- loads checkpoint → runs evaluation on dataset → possibly writes additional metrics
- grad_cam_results.py & grad_cam_video_results.py
- load checkpoint + a sample image → forward pass + Grad-CAM hook via utils or dedicated GradCAM implementation → write overlays/videos

##### Architectural patterns & design principles
- Modular design: clear separation between data loading, model initialization, training logic, and visualization.
- Factory pattern in `cnn_models.py` to decouple model selection from training logic.
- Single-responsibility modules: each file handles one concern.
- Use of configuration file (config.py) for hyperparameters centralization.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CLI Layer"
        CLI_User["User"]:::cli
        Split["split_dataset.py"]:::cli
        Train["train.py"]:::cli
        Test["test.py"]:::cli
        GCStatic["grad_cam_results.py"]:::cli
        GCVideo["grad_cam_video_results.py"]:::cli
    end

    subgraph "Core Library"
        Config["config.py"]:::core
        DataLoader["data_loader.py"]:::core
        ModelFactory["cnn_models.py"]:::core
        Metrics["metrics.py"]:::core
        Utils["utils.py"]:::core
    end

    subgraph "External Libraries"
        PyTorch["PyTorch/torchvision"]:::ext
        ImageIO["OpenCV/PIL"]:::ext
        PlotLib["Matplotlib/Seaborn"]:::ext
    end

    subgraph "Data Storage"
        Raw["Raw Dataset Dir"]:::storage
        Organized["Train/Val Folders"]:::storage
        Checkpoints["Checkpoints (.pth)"]:::storage
        Samples["samples1/"]:::storage
        Examples["examples/"]:::storage
        subgraph "Examples Subdirs"
            Alexnet["alexnet-gradresults"]:::storage
            Densenet["densenet-gradresults"]:::storage
            Efficient["efficientnetv2-gradresults"]:::storage
            Regnet["regnet-gradresults"]:::storage
            Resnet["resnet-gradresults"]:::storage
            Resnext["resnext-gradresults"]:::storage
            Shufflenet["shufflenet-gradresults"]:::storage
            Squeezenet["squeezenet-gradresults"]:::storage
            Vgg["vgg-gradresults"]:::storage
        end
    end

    %% User to CLI
    CLI_User -->|runs| Split
    CLI_User -->|runs| Train
    CLI_User -->|runs| Test
    CLI_User -->|runs| GCStatic
    CLI_User -->|runs| GCVideo

    %% split_dataset flow
    Split -->|reads| Raw
    Split -->|writes| Organized
    Split -->|uses| Config
    Split -->|calls| DataLoader

    %% train.py flow
    Train -->|uses| Config
    Train -->|calls| DataLoader
    Train -->|calls initialize_model| ModelFactory
    Train -->|imports| PyTorch
    Train -->|saves| Checkpoints
    Train -->|generates| Examples
    Train -->|plots| PlotLib

    %% test.py flow
    Test -->|uses| Config
    Test -->|calls| DataLoader
    Test -->|calls initialize_model| ModelFactory
    Test -->|uses| Metrics
    Test -->|loads| Checkpoints
    Test -->|writes| Examples

    %% grad_cam_results.py flow
    GCStatic -->|uses| Config
    GCStatic -->|calls initialize_model| ModelFactory
    GCStatic -->|uses| Utils
    GCStatic -->|loads| Checkpoints
    GCStatic -->|reads| Samples
    GCStatic -->|writes| Examples
    GCStatic -->|uses| PyTorch
    GCStatic -->|processes| ImageIO

    %% grad_cam_video_results.py flow
    GCVideo -->|uses| Config
    GCVideo -->|calls initialize_model| ModelFactory
    GCVideo -->|uses| Utils
    GCVideo -->|loads| Checkpoints
    GCVideo -->|reads| Samples
    GCVideo -->|writes| Examples
    GCVideo -->|uses| PyTorch
    GCVideo -->|processes| ImageIO

    %% Core modules dependencies
    DataLoader -->|loads/saves images| ImageIO
    ModelFactory -->|builds model| PyTorch
    Metrics -->|plots metrics| PlotLib
    Utils -->|plots/checkpoints| PlotLib
    Utils -->|image I/O| ImageIO

    %% Examples subdirs grouping
    Examples --> Alexnet
    Examples --> Densenet
    Examples --> Efficient
    Examples --> Regnet
    Examples --> Resnet
    Examples --> Resnext
    Examples --> Shufflenet
    Examples --> Squeezenet
    Examples --> Vgg

    click Split "https://github.com/harry-kit/image-classification-on-small-datasets-in-pytorch/blob/main/split_dataset.py"
    click Train "https://github.com/harry-kit/image-classification-on-small-datasets-in-pytorch/blob/main/train.py"
    click Test "https://github.com/harry-kit/image-classification-on-small-datasets-in-pytorch/blob/main/test.py"
    click GCStatic "https://github.com/harry-kit/image-classification-on-small-datasets-in-pytorch/blob/main/grad_cam_results.py"
    click GCVideo "https://github.com/harry-kit/image-classification-on-small-datasets-in-pytorch/blob/main/grad_cam_video_results.py"
    click Config "https://github.com/harry-kit/image-classification-on-small-datasets-in-pytorch/blob/main/config.py"
    click DataLoader "https://github.com/harry-kit/image-classification-on-small-datasets-in-pytorch/blob/main/data_loader.py"
    click ModelFactory "https://github.com/harry-kit/image-classification-on-small-datasets-in-pytorch/blob/main/cnn_models.py"
    click Metrics "https://github.com/harry-kit/image-classification-on-small-datasets-in-pytorch/blob/main/metrics.py"
    click Utils "https://github.com/harry-kit/image-classification-on-small-datasets-in-pytorch/blob/main/utils.py"
    click Samples "https://github.com/harry-kit/image-classification-on-small-datasets-in-pytorch/tree/main/samples1/"
    click Examples "https://github.com/harry-kit/image-classification-on-small-datasets-in-pytorch/tree/main/examples/"
    click Alexnet "https://github.com/harry-kit/image-classification-on-small-datasets-in-pytorch/tree/main/examples/alexnet-gradresults"
    click Densenet "https://github.com/harry-kit/image-classification-on-small-datasets-in-pytorch/tree/main/examples/densenet-gradresults"
    click Efficient "https://github.com/harry-kit/image-classification-on-small-datasets-in-pytorch/tree/main/examples/efficientnetv2-gradresults"
    click Regnet "https://github.com/harry-kit/image-classification-on-small-datasets-in-pytorch/tree/main/examples/regnet-gradresults"
    click Resnet "https://github.com/harry-kit/image-classification-on-small-datasets-in-pytorch/tree/main/examples/resnet-gradresults"
    click Resnext "https://github.com/harry-kit/image-classification-on-small-datasets-in-pytorch/tree/main/examples/resnext-gradresults"
    click Shufflenet "https://github.com/harry-kit/image-classification-on-small-datasets-in-pytorch/tree/main/examples/shufflenet-gradresults"
    click Squeezenet "https://github.com/harry-kit/image-classification-on-small-datasets-in-pytorch/tree/main/examples/squeezenet-gradresults"
    click Vgg "https://github.com/harry-kit/image-classification-on-small-datasets-in-pytorch/tree/main/examples/vgg-gradresults"

    classDef cli fill:#D6EAF8,stroke:#1B4F72,color:#1B2631
    classDef core fill:#D5F5E3,stroke:#145A32,color:#0B5345
    classDef ext fill:#FAD7A0,stroke:#7E5109,color:#6E2C00
    classDef storage fill:#E5E7E9,stroke:#566573,color:#1C2833
```
