Metadata-Version: 2.4
Name: ugvnet
Version: 0.1.0
Summary: UGVNet: Universal Gradient Vision Network for Skin Disease Classification
Author: Mizanur Rahman Sajid
License-Expression: MIT
Project-URL: Homepage, https://github.com/mizanur-sajid/UGVNet
Project-URL: Repository, https://github.com/mizanur-sajid/UGVNet
Project-URL: Issues, https://github.com/mizanur-sajid/UGVNet/issues
Project-URL: Documentation, https://github.com/mizanur-sajid/UGVNet#readme
Keywords: deep-learning,skin-disease,dermatology,image-classification,convolutional-neural-network,pytorch,medical-imaging,computer-vision
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Healthcare Industry
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.0
Requires-Dist: torchvision>=0.15
Requires-Dist: numpy>=1.24
Requires-Dist: Pillow>=10.0
Requires-Dist: tqdm>=4.65
Requires-Dist: scikit-learn>=1.3
Requires-Dist: matplotlib>=3.7
Requires-Dist: seaborn>=0.12
Provides-Extra: full
Requires-Dist: pandas>=2.0; extra == "full"
Requires-Dist: pyyaml>=6.0; extra == "full"
Requires-Dist: onnx>=1.14; extra == "full"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

<p align="center">
  <h1 align="center">UGVNet — Universal Gradient Vision Network</h1>
  <p align="center">
    A lightweight CNN architecture for dermatological image classification
  </p>
</p>

<p align="center">
  <a href="https://pypi.org/project/ugvnet/"><img src="https://img.shields.io/pypi/v/ugvnet?style=for-the-badge&logo=pypi&logoColor=white&color=3775A9" alt="PyPI"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.12+-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python 3.12+"></a>
  <a href="https://pytorch.org/"><img src="https://img.shields.io/badge/PyTorch-2.x-EE4C2C?style=for-the-badge&logo=pytorch&logoColor=white" alt="PyTorch"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-22C55E?style=for-the-badge" alt="MIT License"></a>
</p>

---

**UGVNet** (Universal Gradient Vision Network) is a custom, lightweight convolutional neural network engineered for automated classification of common inflammatory and infectious skin diseases. The architecture combines depthwise separable convolutions, squeeze‑and‑excitation channel attention, and multi‑scale feature refinement to achieve efficient lesion‑level feature extraction from dermatoscopic images.

> **Status:** This project is under active research. Model performance is being iteratively improved through architecture refinements and training strategy optimization.

---

## Table of Contents

- [Key Features](#key-features)
- [Architecture](#architecture)
- [Dataset](#dataset)
- [Project Structure](#project-structure)
- [Installation](#installation)
- [Usage](#usage)
  - [Training](#training)
  - [Evaluation](#evaluation)
  - [Notebooks](#notebooks)
- [Results](#results)
- [Model Export](#model-export)
- [Future Work](#future-work)
- [Citation](#citation)
- [Author](#author)
- [License](#license)

---

## Key Features

- **Custom architecture** — purpose‑built for dermatological image classification; not a fine‑tuned transfer‑learning model.
- **Lightweight** — ~2.17 M trainable parameters; designed with edge‑deployment in mind.
- **Depthwise separable convolutions** — reduces computational cost while preserving representational capacity.
- **Squeeze‑and‑excitation attention** — adaptive channel recalibration to emphasize clinically relevant features.
- **Multi‑scale feature refinement** — parallel 3×3, 5×5, and 7×7 branches capture textures, patterns, and broader context.
- **Multi‑format export** — supports PyTorch, TensorFlow (SavedModel), and ONNX.
- **End‑to‑end pipeline** — dataset preparation, training, evaluation, explainability, and visualization in a single codebase.

---

## Architecture

UGVNet follows a sequential, five‑stage topology:

```
Input (3 × 224 × 224)
        │
   ┌────┴────┐
   │  Stem   │   2× ConvBNAct → 32 → 64 channels
   └────┬────┘
        │
   ┌────┴────┐
   │ Stage 1 │   2× UGVBlock (64 → 96), stride‑2 downsampling
   └────┬────┘
        │
   ┌────┴────┐
   │ Stage 2 │   2× UGVBlock (96 → 160), stride‑2 downsampling
   └────┬────┘
        │
   ┌────┴────┐
   │ Stage 3 │   2× UGVBlock (160 → 256), stride‑2 downsampling
   └────┬────┘
        │
   ┌────┴────────────┐
   │  Refinement     │   MultiScaleBlock + SE Attention + Residual
   └────┬────────────┘
        │
   Global Avg Pool → Dropout → Linear (256 → num_classes)
```

### Core Building Blocks

| Component | Description |
|---|---|
| **ConvBNAct** | Conv2D → BatchNorm → GELU activation |
| **DepthwiseSeparableConv** | Depthwise conv + pointwise conv for efficiency |
| **SqueezeExcitation** | Channel attention via global pooling → FC → Sigmoid gating |
| **UGVBlock** | DepthwiseSeparableConv → SE Attention → Residual addition → GELU |
| **MultiScaleBlock** | Parallel 3×3 / 5×5 / 7×7 branches → concatenation → 1×1 fusion |
| **FeatureRefinementBlock** | MultiScaleBlock → SE Attention → Residual addition → GELU |

All weights are initialized using Kaiming Normal (Conv2d), constant (BatchNorm), and Normal (Linear).

---

## Dataset

UGVNet is trained on a curated dermatological dataset comprising **1,710 images** across **6 classes** of common skin conditions.

| Class | Abbreviation |
|---|---|
| Atopic Dermatitis | AD |
| Contact Dermatitis | CD |
| Eczema | EC |
| Scabies | SC |
| Seborrheic Dermatitis | SD |
| Tinea Corporis | TC |

### Split Distribution

| Split | Images |
|---|---|
| Training | 1,194 |
| Validation | 257 |
| Testing | 259 |
| **Total** | **1,710** |

### Image Properties

- **Format:** JPEG · **Color Mode:** RGB · **Resolution:** 512 × 512 px (uniform)
- **File Size:** 9 – 73 KB (avg. 28 KB)
- **Corrupted Images:** 0

---

## Project Structure

```
UGVNet/
├── ugvnet/                         # Source package
│   ├── models/
│   │   ├── layers.py               # ConvBNAct, DepthwiseSeparableConv, SqueezeExcitation
│   │   ├── blocks.py               # UGVBlock, MultiScaleBlock, FeatureRefinementBlock
│   │   └── ugvnet.py               # Main UGVNet model class
│   ├── training/
│   │   ├── trainer.py              # Training loop
│   │   ├── losses.py               # Loss functions
│   │   └── scheduler.py            # Learning rate scheduling
│   ├── evaluation/
│   │   ├── evaluator.py            # Model evaluation pipeline
│   │   ├── metrics.py              # Precision, Recall, F1, ROC‑AUC, etc.
│   │   └── explainability.py       # XAI / interpretability tools
│   ├── visualization/
│   │   └── plots.py                # Training curves, confusion matrices, etc.
│   ├── utils/
│   │   ├── helpers.py              # General utilities
│   │   ├── logger.py               # Logging utilities
│   │   └── seed.py                 # Reproducibility / random seed management
│   ├── augmentation.py             # Data augmentation strategies
│   ├── preprocessing.py            # Image preprocessing pipeline
│   ├── dataset.py                  # Dataset loading
│   └── config.py                   # Configuration management
│
├── datasets/
│   ├── raw/                        # Original images (train / validation / test splits)
│   └── processed/                  # Preprocessed images
│
├── models/
│   ├── checkpoints/                # Training checkpoints
│   └── final/                      # Production‑ready weights
│       └── UGVNet_final.pth        # Final trained model (~8.7 MB)
│
├── notebooks/
│   ├── 01_dataset_preparation.ipynb
│   ├── 02_model_development_training.ipynb
│   └── 03_evaluation_explainability.ipynb
│
├── figures/                        # Generated plots and visualizations
├── reports/                        # Evaluation reports (CSV, JSON, XLSX)
├── exports/                        # Exported models (PyTorch, TensorFlow, ONNX)
├── logs/                           # Training logs
├── docs/                           # Additional documentation
├── LICENSE
└── README.md
```

---

## Installation

> **Prerequisites:** Python 3.12+, pip, and (optionally) a CUDA‑capable GPU.

### From PyPI (recommended)

```bash
pip install ugvnet
```

With all optional dependencies (visualization, evaluation, data processing):

```bash
pip install ugvnet[full]
```

### From Source (development)

```bash
# Clone the repository
git clone https://github.com/mizanur-sajid/UGVNet.git
cd UGVNet

# (Recommended) Create and activate a virtual environment
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

# Install in editable mode with dev dependencies
pip install -e ".[dev,full]"
```

---

## Usage

### Training

Launch the training pipeline with default or custom hyperparameters:

```bash
python -m ugvnet.training.trainer --config config.yaml
```

Training logs, checkpoints, and learning‑rate curves are saved to `logs/` and `models/checkpoints/`.

### Evaluation

Evaluate a trained checkpoint and generate performance reports:

```bash
python -m ugvnet.evaluation.evaluator --checkpoint models/final/UGVNet_final.pth
```

Generated reports (confusion matrices, ROC curves, classification reports) are saved to `reports/` and `figures/`.

### Notebooks

Three Jupyter notebooks provide a guided, end‑to‑end walkthrough:

| Notebook | Purpose |
|---|---|
| `01_dataset_preparation.ipynb` | Data loading, exploration, integrity checks, and augmentation preview |
| `02_model_development_training.ipynb` | Architecture definition, hyperparameter setup, and training execution |
| `03_evaluation_explainability.ipynb` | Metrics computation, visualization, and explainability analysis |

---

## Results

> ⚠️ **The results below reflect early baseline training. Active optimization is in progress.**

| Metric | Value |
|---|---|
| **Test Accuracy** | 37.84% |
| **Weighted Precision** | 33.33% |
| **Weighted Recall** | 37.84% |
| **Weighted F1 Score** | 34.77% |
| **Mean ROC AUC** | 70.84% |
| **Total Parameters** | 2,166,328 |

### Per‑Class Performance

| Class | Precision | Recall | F1 Score | Support |
|---|---|---|---|---|
| Atopic Dermatitis (AD) | 0.00 | 0.00 | 0.00 | 11 |
| Contact Dermatitis (CD) | 0.35 | 0.29 | 0.32 | 72 |
| Eczema (EC) | 0.36 | 0.37 | 0.36 | 70 |
| Scabies (SC) | 0.45 | 0.75 | 0.57 | 52 |
| Seborrheic Dermatitis (SD) | 0.00 | 0.00 | 0.00 | 12 |
| Tinea Corporis (TC) | 0.30 | 0.29 | 0.29 | 42 |

---

## Model Export

Trained models can be exported to multiple frameworks for deployment:

```
exports/
├── pytorch/        # PyTorch (.pt / .pth)
├── tensorflow/     # TensorFlow SavedModel
└── onnx/           # ONNX format
```

---

## Future Work

- **Architecture refinement** — iterative improvements to UGVBlock design and training strategies to boost accuracy.
- **Dataset expansion** — incorporate rare dermatological conditions and larger public datasets.
- **Advanced augmentation** — explore CutMix, MixUp, and domain‑specific augmentation techniques.
- **Edge deployment** — optimize inference for mobile and embedded devices via quantization and pruning.
- **Explainability** — integrate Grad‑CAM, SHAP, and other XAI techniques to improve clinical interpretability.

---

## Citation

If you use UGVNet in your research, please cite:

```bibtex
@software{sajid2026ugvnet,
  author       = {Mizanur Rahman Sajid},
  title        = {UGVNet: Universal Gradient Vision Network for Skin Disease Classification},
  year         = {2026},
  url          = {https://github.com/mizanur-sajid/UGVNet}
}
```

---

## Author

**Mizanur Rahman Sajid**

---

## License

This project is licensed under the [MIT License](LICENSE). See the `LICENSE` file for details.
