AmirhosseinHonardoust/Image-Classification-CNN
AmirhosseinHonardoust/Image-Classification-CNN has 27 GitHub stars and 0 forks. GitHot measured 0 stars in 24 hours and 0 in 7 days. Last checked 2026-11-21 19:08 UTC. Last push 2026-09-06.
What you can do
- CNN architecture with two convolution + ReLU + pooling blocks followed by fully connected layers
- Adam optimizer with CrossEntropyLoss
- Early stopping with a configurable patience, paired with best-checkpoint saving
- Typed configuration system (TrainConfig / EvalConfig) merging CLI flags, an optional JSON config file, and defaults
측정된 스타 증가
- in 24h
- 0
- in 7 days
- 0
- in 15 days
- 기록 수집 중
- in 1 month
- 기록 수집 중
서로 겹치는 기간의 순증가량이며 일별 합계가 아닙니다. 측정값이 없으면 비워 둡니다. 스타는 관심도를 나타내며 품질을 보장하지 않습니다.
소개
Image classification with PyTorch using Convolutional Neural Networks (CNNs). Trains on MNIST with convolution, pooling, and fully connected layers. Achieves over 99% accuracy with early stopping and checkpoints. Includes training/evaluation scripts, metrics, confusion matrix, training curves, and sample prediction visualizations.
머신러닝README.md
OriginalAn image classification project built with PyTorch, using a Convolutional Neural Network (CNN) to recognize handwritten digits from the MNIST dataset, with early stopping, best-model checkpointing, config-driven training, evaluation metrics, and visual diagnostics.
Important: This project is an educational computer-vision demo, not a production image-recognition system.
The model, configuration, and reports are designed to demonstrate a clean, well-tested CNN training workflow. MNIST is a small, clean, well-studied benchmark; strong accuracy here does not imply the same architecture would perform well on noisy, real-world, or out-of-distribution images.
Table of Contents
- Project Overview
- What This Project Does
- What This Project Does Not Do
- Key Features
- System Workflow
- Project Structure
- Installation
- Quick Start
- Training and Evaluation
- Configuration
- Model Architecture
- Model Output
- Evaluation Metrics
- Visual Reports
- Testing and CI
- Code Quality
- Limitations
- Responsible Use
- Future Improvements
- Tech Stack
- Author
- License
Project Overview
Image classification is often the first serious computer-vision project people build, but it's easy to stop at "train a model, report accuracy" without building the surrounding workflow that makes a project reproducible and trustworthy:
- a typed, mergeable configuration instead of scattered hard-coded constants
- early stopping and checkpointing so training doesn't overfit or waste time
- consistent metrics written to disk instead of only printed to a terminal
- visual diagnostics that reveal how the model fails, not just whether it does
This project demonstrates an end-to-end, well-structured CNN training workflow on the MNIST handwritten-digit dataset. It includes a configurable training script, a separate evaluation script, typed configuration merging across defaults, JSON files, and the CLI, and a full test suite backed by CI.
The goal is to show how a standard CNN benchmark project can be turned into a clean, reproducible engineering workflow, not just a single accuracy number.
What This Project Does
This project can:
- Train a CNN on the MNIST dataset (28×28 grayscale digit images)
- Apply early stopping and save the best-performing checkpoint
- Merge configuration from CLI flags, a JSON file, and sensible defaults
- Evaluate a trained checkpoint on the test set
- Compute accuracy, macro precision, macro recall, and macro F1
- Generate training curves, a confusion matrix, and sample predictions
- Save all metrics to a machine-readable
metrics.json - Run automated tests and a GitHub Actions CI workflow
What This Project Does Not Do
This project does not:
- Classify arbitrary real-world photographs
- Handle color images, varying resolutions, or complex scenes
- Guarantee similar accuracy on noisy, rotated, or out-of-distribution digits
- Perform data augmentation beyond what is explicitly configured
- Serve the model behind an API or interactive app
- Replace a production-grade computer-vision pipeline
A production image-classification system would need a much larger and more diverse dataset, data augmentation, robustness testing, model serving infrastructure, and ongoing monitoring.
Key Features
- CNN architecture with two convolution + ReLU + pooling blocks followed by fully connected layers
- Adam optimizer with CrossEntropyLoss
- Early stopping with a configurable patience, paired with best-checkpoint saving
- Typed configuration system (
TrainConfig/EvalConfig) merging CLI flags, an optional JSON config file, and defaults - Separate training and evaluation scripts so a checkpoint can be evaluated independently of training
- Automatic MNIST download via torchvision on first run
- Visual diagnostics: training curves, confusion matrix, sample predictions
- Machine-readable metrics written to
metrics.json - Unit tests and GitHub Actions CI
- Pre-commit hooks for Ruff, Black, and mypy
System Workflow
MNIST dataset (auto-downloaded via torchvision)
↓
Config merge (defaults + JSON file + CLI flags)
↓
CNN training (Conv → ReLU → Pool ×2 → Fully Connected)
↓
Adam optimizer + CrossEntropyLoss
↓
Early stopping + best checkpoint (best_cnn.pth)
↓
Evaluation on the test set
↓
Accuracy / precision / recall / F1 (metrics.json)
↓
Training curves, confusion matrix, sample predictions
Project Structure
image-classification-cnn/
│
├── .github/
│ └── workflows/
│ └── ci.yml
│
├── data/ # auto-downloaded MNIST dataset (git-ignored)
│
├── outputs/
│ ├── metrics.json
│ ├── confusion_matrix.png
│ ├── training_curves.png
│ ├── sample_predictions.png
│ └── best_cnn.pth
│
├── src/
│ └── image_classification_cnn/
│ ├── __init__.py
│ ├── class_names.py # shared dataset label constants (e.g. CIFAR10)
│ ├── config.py # typed TrainConfig/EvalConfig + CLI/file/default merge
│ ├── model.py # SimpleCNN architecture
│ ├── train_cnn.py # training script (also installed as `train-cnn`)
│ ├── evaluate.py # evaluation script (also installed as `evaluate-cnn`)
│ └── utils.py # helper functions
│
├── tests/ # pytest suite for the modules above
│
├── .dockerignore
├── .gitignore
├── .pre-commit-config.yaml
├── CONTRIBUTING.md
├── Dockerfile
├── LICENSE
├── Makefile
├── pyproject.toml
├── requirements.txt
├── requirements-dev.txt
├── train_config.example.json
└── README.md
Installation
1. Clone the Repository
git clone https://github.com/AmirhosseinHonardoust/Image-Classification-CNN.git
cd Image-Classification-CNN
2. Create a Virtual Environment
On Windows CMD:
python -m venv .venv
.venv\Scripts\activate
On macOS/Linux:
python -m venv .venv
source .venv/bin/activate
3. Install Requirements
pip install -r requirements.txt
pip install -e .
The pip install -e . step installs the train-cnn and evaluate-cnn
console scripts used below (an editable install, so local code edits take
effect immediately).
For development tools (pytest, Ruff, Black, mypy):
pip install -r requirements-dev.txt
Quick Start
Train the model:
train-cnn --dataset mnist --epochs 10 --batch-size 64 --outdir outputs
Evaluate the trained checkpoint:
evaluate-cnn --model outputs/best_cnn.pth --dataset mnist --outdir outputs
data/ is downloaded automatically by torchvision on first run, and outputs/ is written by the training and evaluation scripts. Both are git-ignored.
Training and Evaluation
The training script downloads MNIST if needed, builds the CNN, trains with early stopping, and writes the best checkpoint:
train-cnn \
--dataset mnist \
--epochs 10 \
--batch-size 64 \
--outdir outputs
Flags can also be supplied from a JSON file:
train-cnn --config train_config.example.json
Any flag passed explicitly on the CLI still overrides the same key from the config file, which itself overrides the built-in defaults.
The evaluation script loads a saved checkpoint and reports metrics on the test split:
evaluate-cnn --model outputs/best_cnn.pth --dataset mnist --outdir outputs
Generated outputs include:
outputs/metrics.json
outputs/training_curves.png
outputs/confusion_matrix.png
outputs/sample_predictions.png
outputs/best_cnn.pth
Docker
A Dockerfile is included for reproducible training without a local Python
environment:
docker build -t image-classification-cnn .
docker run --rm -v "$(pwd)/outputs:/app/outputs" image-classification-cnn
This runs train_cnn.py --config train_config.example.json by default; pass
different args after the image name to override (e.g. --dataset cifar10).
Configuration
Configuration is layered, with each layer overriding the one before it:
built-in defaults → JSON config file (--config) → explicit CLI flags
Example train_config.example.json:
{
"dataset": "mnist",
"epochs": 10,
"batch_size": 64,
"lr": 0.001,
"outdir": "outputs",
"patience": 3
}
| Key | Meaning |
|---|---|
dataset |
Which dataset to train on |
epochs |
Maximum number of training epochs |
batch_size |
Mini-batch size for training and evaluation |
lr |
Learning rate for the Adam optimizer |
outdir |
Directory where checkpoints and reports are written |
patience |
Number of epochs without improvement before early stopping triggers |
This merge behavior is covered by the test suite in tests/, so a change to the merge order or precedence would be caught by CI.
Model Architecture
src/model.py defines a compact CNN sized for 28×28 grayscale input:
| Stage | Operation |
|---|---|
| Block 1 | Conv2d → ReLU → MaxPool2d |
| Block 2 | Conv2d → ReLU → MaxPool2d |
| Head | Flatten → Fully Connected → output logits |
Training uses the Adam optimizer with CrossEntropyLoss. Early stopping monitors validation performance and halts training once it fails to improve for patience consecutive epochs, and the best-performing checkpoint (not necessarily the last epoch) is the one saved to outputs/best_cnn.pth.
Model Output
Running evaluation prints and saves a metrics summary. With the bundled MNIST run:
| Metric | Value |
|---|---|
| Accuracy | 99.35% |
| Precision (macro) | 0.9935 |
| Recall (macro) | 0.9934 |
| F1 Score (macro) | 0.9934 |
These are also written to a machine-readable outputs/metrics.json alongside the checkpoint used to produce them.
Evaluation Metrics
Evaluation runs on the standard MNIST test split, held out from training.
| Metric | Why it matters |
|---|---|
| Accuracy | Overall correctness across all ten digit classes |
| Macro Precision | Average precision treating every digit class equally |
| Macro Recall | Average recall treating every digit class equally |
| Macro F1 | Balances precision and recall across all classes |
MNIST is a clean, balanced, well-studied dataset. High accuracy here reflects strong performance on this benchmark, not a guarantee of similar performance on noisier or more diverse real-world images.
Visual Reports
Training and evaluation charts
| Confusion Matrix | Training Curves |
|---|---|
| Analysis: The confusion matrix shows which digits the model confuses most often on the test set. Even at 99%+ accuracy, the per-class view highlights the handful of visually similar digit pairs that remain hardest. | Analysis: The training curves show loss and accuracy across epochs for both the training and validation sets, making it easy to see where early stopping triggered. |
Sample predictions
| Sample predictions |
|---|
| The sample-predictions grid shows a batch of test digits alongside the model's predicted labels, giving a quick qualitative sanity check beyond the aggregate metrics. |
Testing and CI
Run unit tests locally (this also prints a coverage report, configured in pyproject.toml):
pytest
Run the same checks CI runs, in one step, via the Makefile:
make check
Or individually:
ruff check src tests
black --check src tests
mypy src
pytest
The GitHub Actions workflow (.github/workflows/ci.yml) runs these same checks on every push and pull request:
- dependency installation
- linting with Ruff
- formatting check with Black
- static type checking with mypy
- unit tests with pytest
Code Quality
The project separates responsibilities across modules:
| Module | Purpose |
|---|---|
src/image_classification_cnn/config.py |
Typed TrainConfig / EvalConfig and the defaults → file → CLI merge logic |
src/image_classification_cnn/datasets.py |
Single source of truth for supported datasets (torchvision class, channels, image size, transforms) |
src/image_classification_cnn/model.py |
The SimpleCNN architecture |
src/image_classification_cnn/train_cnn.py |
Training loop, early stopping, checkpoint saving (installed as train-cnn) |
src/image_classification_cnn/evaluate.py |
Loads a checkpoint and computes test-set metrics and charts (installed as evaluate-cnn) |
src/image_classification_cnn/utils.py |
Shared helper functions |
Tooling is configured through pyproject.toml (Ruff, Black, mypy, pytest) and requirements-dev.txt. The package ships a py.typed marker (PEP 561), so downstream projects that import it get type-checking support too. Optional pre-commit hooks (.pre-commit-config.yaml) run the same linting, formatting, and type checks automatically before each commit:
pip install pre-commit
pre-commit install
Limitations
This project has important limitations:
- MNIST is a small, clean, single-domain benchmark, not a real-world image corpus
- The model only handles fixed-size, grayscale, centered digit images
- High accuracy on MNIST does not transfer to noisy, rotated, or occluded inputs
- No data augmentation is applied beyond what is explicitly configured
- The model is not evaluated for robustness against adversarial or out-of-distribution inputs
- There is no inference API or deployment tooling included
The project is strongest as a portfolio demonstration of a clean, well-tested, config-driven CNN training workflow.
Responsible Use
This repository is intended for:
- machine learning and computer-vision education
- learning CNN architecture design and training loops
- practicing config-driven, testable ML project structure
- portfolio demonstration
It should not be used as-is for:
- production image classification or recognition systems
- safety-critical or high-stakes decision-making
- classifying image domains outside handwritten digits without retraining
- any deployment without further validation and testing
Any real deployment would require a larger and more diverse dataset, robustness and fairness evaluation, and a proper serving and monitoring setup.
Future Improvements
Potential next improvements:
- Add support for additional datasets (e.g. Fashion-MNIST, CIFAR-10)
- Add data augmentation (rotation, shift, noise) and measure its effect
- Add a confusion-matrix-driven error analysis report
- Add TensorBoard or Weights & Biases logging
- Add ONNX export and a minimal inference script
- Add Docker support for reproducible training
- Explore deeper architectures and compare against the baseline CNN
Tech Stack
- Python
- PyTorch
- torchvision
- NumPy
- matplotlib
- pytest
- Ruff
- Black
- mypy
- GitHub Actions
Author
Amir Honardoust
GitHub: @AmirhosseinHonardoust
License
This project is licensed under the MIT License. See LICENSE for details.
관련 프로젝트 살펴보기
불러오는 중…