{"id":18340254,"url":"https://github.com/eduardoleao052/cnn-from-scratch","last_synced_at":"2025-08-19T11:07:34.883Z","repository":{"id":207095592,"uuid":"643239041","full_name":"eduardoleao052/CNN-from-scratch","owner":"eduardoleao052","description":"Clear implementation of a CNN from scratch in vanilla python. Feel free to get inspiration for your own projects!","archived":false,"fork":false,"pushed_at":"2024-04-10T19:52:10.000Z","size":14306,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-13T09:45:08.587Z","etag":null,"topics":["computer-vision","deep-learning","machine-learning"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eduardoleao052.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-05-20T14:32:52.000Z","updated_at":"2024-10-26T13:33:58.000Z","dependencies_parsed_at":"2024-12-23T16:37:35.735Z","dependency_job_id":null,"html_url":"https://github.com/eduardoleao052/CNN-from-scratch","commit_stats":null,"previous_names":["eduardoleao052/cv_models","eduardoleao052/cnn-from-scratch"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/eduardoleao052/CNN-from-scratch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eduardoleao052%2FCNN-from-scratch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eduardoleao052%2FCNN-from-scratch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eduardoleao052%2FCNN-from-scratch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eduardoleao052%2FCNN-from-scratch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eduardoleao052","download_url":"https://codeload.github.com/eduardoleao052/CNN-from-scratch/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eduardoleao052%2FCNN-from-scratch/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271143335,"owners_count":24706344,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-19T02:00:09.176Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["computer-vision","deep-learning","machine-learning"],"created_at":"2024-11-05T20:21:49.680Z","updated_at":"2025-08-19T11:07:34.844Z","avatar_url":"https://github.com/eduardoleao052.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CNN From Scratch in Vanilla Python\n- Use this repo to __train and test your own CNN__. Feel free to browse the classes in [layers.py](layers.py). They contain a full CNN implementation in __less than 50 lines of code__.\n\n## 1. Project Structure\n\n- `models/` : Folder which stores the saved models. Further explaination in section 2.\n\n- `layers.py` : File containing every layer of the CNN. Each layer is a class with a `.forward` and `.backward` method.\n\n- `model.py` : File with the `Model` class.\n  \n- `run.py` : Script ran by the `./run.sh` command. Trains the model.\n    \n- `utils.py` : File with helper functions and classes.\n\n## 2. Running it Yourself\n\u003cdetails\u003e\n\u003csummary\u003e \u003ch3\u003eRequirements\u003c/h3\u003e \u003c/summary\u003e\n\n- The only packaged used for the model is numpy. Other libraries are listed on `requirements.txt`.\n- To setup and join a miniconda virtual environment, run on terminal:\n```\nconda create -n environment_name python=3.8\nconda activate environment_name\n```\n- The requirements can be installed on a virtual environment with the command\n```\npip install -r requirements.txt\n```\n- To run, install the necessary requirements and a image dataset (.csv format).\n- There must be a training and a test files. The files must have the label as the first column, and the features as the remaining columns.\n- You can download your image file in the data directory.\n\u003e **Notes:** __1:__ The training is only implemented on CPU (no torch, tensorflow or CUDA support). __2:__ Scipy is used for faster implementation of Correlation and Convolution. I also made fully numpy-based implementations. They work and are in the `functions.py` file. The scipy implementation is only being used due to efficiency gains in training.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e \u003ch3\u003eTraining\u003c/h3\u003e \u003c/summary\u003e\n  \n- To train a CNN on your image dataset, go into run.sh and set the flag to `--train` and choose the following arguments:\n  - `--train_data` (full path to your training data file)                                      \u003cb\u003e[OPTIONAL]\u003c/b\u003e\n  - `--test_data` (full path to your test data file)                                           \u003cb\u003e[OPTIONAL]\u003c/b\u003e\n  - `--epochs` (number of full passes through training data @ traintime)                       \u003cb\u003e[OPTIONAL]\u003c/b\u003e\n  - `--batch_size` (size of the batch (number of images per batch))                            \u003cb\u003e[OPTIONAL]\u003c/b\u003e\n  - `--augmenter_ratio` (1 or 4, 1:ratio is how many times training dataset will be augmented) \u003cb\u003e[OPTIONAL]\u003c/b\u003e\n  - `--to_path` (path to .json file where model parameters will be stored for later use)       \u003cb\u003e[OPTIONAL]\u003c/b\u003e\n```\npython3 run.py --train --train_data=path_to_train_data --test_data=path_to_test_data --to_path=name_of_json_that_will_store_model.json\n```\n- Run on terminal:\n```\n./run.sh\n```\n- Whenever you feel like the validation accuracy printed is good enough, you can kill the training at any time. This will NOT corrupt the model saved in the given .json file, and you may proceed to testing and using the model :).\n\u003e **Note:** If you want to alter layers/dimensions, do so in the `run.py` file, with the `.add(Layer)` method.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e \u003ch3\u003eTesting\u003c/h3\u003e \u003c/summary\u003e\n\n  - To test a CNN on your image dataset, go into run.sh and set the flag to `--test` and choose the following arguments:\n  - `--test_data` (full path to your test data file) \n  - `--from_path` (path to file with model parameters to be loaded)\n```\npython3 run.py --test --test_data=path_to_test_data --from_path=name_of_json_with_model.json\n```\n- Run on terminal:\n```\n./run.sh\n```\n\u003e **Note:** The accuracy score for these tests will usually be lower than the accuracy scores achieved with the training and validation sets.\n\n\u003c/details\u003e\n\n## 3. Results\n- The full Convolutional Neural Network implementation achieved \u003cb\u003e99.36%\u003c/b\u003e accuracy on the validation set of the MNIST handwritten digit dataset.\n- This implementation is NOT the one presented in the `run.py` file.\n- The \u003cb\u003e99.36%\u003c/b\u003e implementation used 5 kernels, and 256-dimensioned Dense layers.\n- The training time was ~25h on my M2 CPU.\n  \n\u003cp align=\"left\", style=\"margin-left:35px;\"\u003e\n  \u003cimg src=\"assets/model_accuracy_large.png\" width=\"900\"/\u003e\n\u003c/p\u003e\n- With the implementation present in run.py, I achieved \u003cb\u003e96,1%\u003c/b\u003e in ~15min of training (M2 CPU) on the MNIST dataset.\n\n\u003cp align=\"left\", style=\"margin-left:35px;\"\u003e\n  \u003cimg src=\"assets/model_accuracy_small.png\" width=\"900\"/\u003e\n\u003c/p\u003e\n- Thank you for reading!\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feduardoleao052%2Fcnn-from-scratch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feduardoleao052%2Fcnn-from-scratch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feduardoleao052%2Fcnn-from-scratch/lists"}