{"id":26917615,"url":"https://github.com/edcalderin/handwritten-digit-recognition","last_synced_at":"2026-04-16T19:47:09.062Z","repository":{"id":226947664,"uuid":"770023950","full_name":"edcalderin/handwritten-digit-recognition","owner":"edcalderin","description":"Detect handwritten numbers using cosine similarity metric","archived":false,"fork":false,"pushed_at":"2025-07-20T16:17:21.000Z","size":9836,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-20T18:14:05.197Z","etag":null,"topics":["cosine-similarity","docker","handwritten-digit-recognition","poetry","python","streamlit"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/edcalderin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null}},"created_at":"2024-03-10T17:57:25.000Z","updated_at":"2025-07-20T16:17:21.000Z","dependencies_parsed_at":"2025-06-01T09:41:24.033Z","dependency_job_id":"0916dd59-d8e7-4d6c-a008-24e1ec1a86a0","html_url":"https://github.com/edcalderin/handwritten-digit-recognition","commit_stats":null,"previous_names":["edcalderin/handwritten-number-detector","edcalderin/handwritten-digit-recognition"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/edcalderin/handwritten-digit-recognition","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edcalderin%2Fhandwritten-digit-recognition","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edcalderin%2Fhandwritten-digit-recognition/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edcalderin%2Fhandwritten-digit-recognition/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edcalderin%2Fhandwritten-digit-recognition/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/edcalderin","download_url":"https://codeload.github.com/edcalderin/handwritten-digit-recognition/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edcalderin%2Fhandwritten-digit-recognition/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31902123,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T18:22:33.417Z","status":"ssl_error","status_checked_at":"2026-04-16T18:21:47.142Z","response_time":69,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["cosine-similarity","docker","handwritten-digit-recognition","poetry","python","streamlit"],"created_at":"2025-04-01T20:50:08.283Z","updated_at":"2026-04-16T19:47:09.035Z","avatar_url":"https://github.com/edcalderin.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Handwritten Digit Recognition with Cosine Similarity\n\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n\n![Cover image](./images/cover.jpg)\n*\u003cp align=\"center\"\u003eImage credits: \u003ca href='https://aigeekprogrammer.com/keras-python-mnist-handwritten-digit-recognition/'\u003eAI Geek Programmer article\u003c/a\u003e\u003c/p\u003e*\n\n## Table of Contents\n\n* [Problem statement](#problem-statement)\n* [Directory layout](#directory-layout)\n* [Running the app with Docker (Recommended)](#running-the-app-with-docker-recommended)\n* [Running the app manually](#running-the-app-manually)\n* [Quality code](#quality-code)\n* [Checkpoints](#checkpoints)\n* [References](#references)\n\n## Problem statement\n\nIn this project, I introduce a different and naive approach to the popular problem of handwritten digit recognition, widely used in Machine Learning and Convolutional Neural Network by enthusiasts who start in this field. Maybe it is unnecessary to describe the idea behind as you have probably read, seen or implemented this kind of problems on your own, but in this opportunity I decided go through an algebraic solution to identify digits written by hand making usage of the cosine similarity metric [(See on references)](#references). \n\nThe metric is calculated by measuring the similarity between two vectors and corresponds to the following formula:\n\n$$ cos(\\theta) = { \n    \\sum\\limits_{i=0}^{n-1} A_iB_i\n    \\over \n    \\sqrt{\\sum\\limits_{i=0}^{n-1} {A_i^2}} \\sqrt{\\sum\\limits_{i=0}^{n-1} {B_i^2}}\n}\n$$\n\nWhere *A* and *B* represent bi-dimensional arrays, denoting the digit drawn by the user and the original digit intended to be the expected figure, respectively. Though these can interchanged in the formula.\n\nI have designed a minimal yet functional Streamlit application to showcase this algorithm: Users select a number from a dropdown menu and then proceed to draw the selected number. The result will appear after press the `Compare` button. Additionally, I have categorized the results into three groups based on the score: **Excellent** (`score \u003e 0.7`), **Good** (`score \u003e 0.4`) and **Incorrect** (`score \u003c 0.4`).\n\nThe animation below illustrates how the application works:\n\n![Alt text](./images/app.gif)\n\nTo sum it up, the applications of the cosine similarity extend beyond simple array comparisons, it is predominantly used in Large Language Models, Recommender Systems, Information Retrieval and various other domains. Therefore, you can leverage its potential to develop a wide range of projects.\n\n## Directory layout\n\n```\n.\n├── images              # Assets for the project\n│   └── digits          # Images of digits from 0 to 9\n├── src                 # Directory with source python files\n│   └── array_digits    # Directory with files representing arrays of digits (zero.py to nine.py)\n└── tests               # Directory contianint test files\n\n5 directories\n```\n\n## Running the app with Docker (Recommended)\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/edcalderin/Handwritten-digit-recognition.git\n```\n2. Start Docker Desktop\n\n3. Build and run the docker image:\n```bash\ndocker build -t digit-recognition .\ndocker run -it --rm -p 8501:8501 digit-recognition\n```\n\n3. Go to `http://localhost:8501`\n\n## Running the app manually\n\n\u003e :warning: You will need **Python 3.12** installed on your system in order to reproduce this app manually.\n\nRun the following commands from root project directory:\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/edcalderin/Handwritten-digit-recognition.git\n```\n2. Install Poetry (Skip this if you already installed it)\n```bash\npip install poetry\n```\n3. Create and activate environment:\n```bash\npoetry shell\n```\n4. Install dependencies:\n```bash\npoetry install\n```\n5. Run the streamlit command:\n```bash\npython -m streamlit run src/app.py\n```\n6. Go to `http://localhost:8501`\n\n## Quality code\n\nThis project used `ruff` and `pytest` to ensure the quality code:\n\n* Linter:\n```bash\nruff check .\n```\n\n* Tests:\n```bash\npython -m pytest tests\n```\n\n\n## Checkpoints\n\n- [x] Problem description\n- [x] Reproducibility\n- [x] Dependency and enviroment management\n- [x] Containerization (Docker with multi-stage)\n- [x] Linter\n- [x] Unit tests\n- [x] CI/CD workflow (Linter and Unit tests)\n- [ ] Cloud deployment\n\n## References\n\n* https://en.wikipedia.org/wiki/Cosine_similarity","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedcalderin%2Fhandwritten-digit-recognition","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fedcalderin%2Fhandwritten-digit-recognition","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedcalderin%2Fhandwritten-digit-recognition/lists"}