CNN-FS

🧠 CNN from Scratch

This project is a simple Convolutional Neural Network (CNN) implemented entirely from scratch using only low-level libraries like NumPy, PIL, and SciPy— no deep learning frameworks (e.g., TensorFlow or PyTorch) are used. It includes image preprocessing, convolution and pooling operations, ReLU and softmax activations, forward/backward propagation, and a fully connected classifier.

CNN Architecture

📦 Releases

Version	Stable	Test a trained model
0.1.0	✅	Test

🚀 Features

Manual image preprocessing (RGB separation, resizing, normalization)
Handcrafted convolution and max-pooling operations
Fully connected layers (L1, L2, and output)
Softmax + Cross-Entropy Loss
Mini-batch gradient descent with backpropagation
Model saving/loading using pickle
Class prediction on new images

🖼 Dataset Structure

Make sure your dataset folder is structured like this:

data/
├── class1/
│   ├── image1.png
│   ├── image2.png
├── class2/
│   ├── image1.png
│   ├── image2.png
├── class../
│   ├── ..
..

Each subfolder represents a class (e.g., cat, dog), and contains sample images.

To help you get started, we’ve included a starter data folder with example class directories.

🧪 How It Works

Image Preprocessing:
- Each image is resized to a fixed size and normalized.
- Filters (e.g., sharpening, edge detection) are applied using 2D convolution.
- ReLU activation and 2×2 max-pooling reduce spatial dimensions.
Feature Vector:
- Flattened pooled feature maps are fed into fully connected layers.
Feedforward + Softmax:
- Dense layers compute activations followed by a softmax for classification.
Backpropagation:
- Gradients are computed layer-by-layer.
- Weights and biases are updated using basic gradient descent.

🛠 Setup

pip install git+https://github.com/77AXEL/CNN-FS.git

✅ Training

from cnnfs.model import CNN

model = CNN()
model.init(
    image_size=64,
    batch_size=32,
    h1=128,
    h2=64,
    learning_rate=0.001,
    epochs=400,
    dataset_path="data",
    max_image=200,
    filters=[
        [[0, -1, 0], [-1, 5, -1], [0, -1, 0]],
        [[1, 0, -1], [1, 0, -1], [1, 0, -1]],
        [[-1, -1, -1], [-1, 8, -1], [-1, -1, -1]]
    ]
)
model.load_dataset()
model.train_model()
model.save_model()

🔍 Predicting New Images

model.load_model("model.bin")
prediction = model.predict("test_images/mycat.png")
print("Predicted class:", prediction)

💡 Example Filters Used

[ [0, -1,  0],   Sharpen
  [-1, 5, -1],
  [0, -1,  0] ]

[ [1,  0, -1],   Edge detection
  [1,  0, -1],
  [1,  0, -1] ]

[[-1, -1, -1],   Laplacian
 [-1,  8, -1],
 [-1, -1, -1] ]

📊 Performance

Metric	Value (example)
Accuracy	~90% (binary class)
Epochs	10–50
Dataset	Custom / ~8000 imgs

Note that a larger dataset and more training epochs typically lead to higher accuracy.

🧠 Concepts Demonstrated

CNNs without frameworks
Data vectorization
Forward and backward propagation
Optimization from scratch
One-hot encoding for multi-class classification

📦 Dependencies

📜 License

MIT License — feel free to use, modify, and share.

🤝 Contributing

PRs are welcome! You can help:

Add evaluation functions
Improve filter design
Extend to grayscale or multi-channel separately
Parallelize dataset loading

This site is open source. Improve this page.