{"id":15379974,"url":"https://github.com/iansan5653/open-mcr","last_synced_at":"2025-04-10T00:18:49.241Z","repository":{"id":36657785,"uuid":"206365601","full_name":"iansan5653/open-mcr","owner":"iansan5653","description":":pencil: Exam bubble sheet scorer. Created with OpenCV and Python.","archived":false,"fork":false,"pushed_at":"2023-12-09T00:41:14.000Z","size":52031,"stargazers_count":175,"open_issues_count":21,"forks_count":57,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-10T00:18:20.845Z","etag":null,"topics":["computer-vision","education","exam-sheets","extract","machine","oer","omr","open-educational-resources","opencv","optical-mark-recognition","python","scanner"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iansan5653.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":".github/funding.yml","license":"license.txt","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},"funding":{"github":"iansan5653"}},"created_at":"2019-09-04T16:36:19.000Z","updated_at":"2025-03-25T21:51:43.000Z","dependencies_parsed_at":"2024-10-31T19:33:12.095Z","dependency_job_id":null,"html_url":"https://github.com/iansan5653/open-mcr","commit_stats":{"total_commits":150,"total_committers":6,"mean_commits":25.0,"dds":"0.23333333333333328","last_synced_commit":"2d54ed846699b6f51ce5efa0284cb1961c2369e7"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iansan5653%2Fopen-mcr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iansan5653%2Fopen-mcr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iansan5653%2Fopen-mcr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iansan5653%2Fopen-mcr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iansan5653","download_url":"https://codeload.github.com/iansan5653/open-mcr/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248131359,"owners_count":21052822,"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","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","education","exam-sheets","extract","machine","oer","omr","open-educational-resources","opencv","optical-mark-recognition","python","scanner"],"created_at":"2024-10-01T14:20:35.665Z","updated_at":"2025-04-10T00:18:49.219Z","avatar_url":"https://github.com/iansan5653.png","language":"Python","funding_links":["https://github.com/sponsors/iansan5653"],"categories":[],"sub_categories":[],"readme":"## ![OpenMCR](src/assets/wordmark.png)\n\n### _Free and Open-Source Multiple Choice Exam Reader_\n\n[![Continuous Integration](https://github.com/iansan5653/open-mcr/actions/workflows/continuous_integration.yml/badge.svg)](https://github.com/iansan5653/open-mcr/actions/workflows/continuous_integration.yml)\n\n\u003e **Warning**\n\u003e As per the license of this software, no warranty is implied. The software is\n\u003e stable but there still may be bugs. Given that students' grades are at stake,\n\u003e please be sure to audit the results - particularly when working with low-quality scans.\n\n## Background\n\nCommercially available OMR (optical mark recognition) exam sheets, scanners, and\nprocessing software can cost educators and educational institutions thousands of\ndollars per year. In response to this, OpenMCR has been developed as a free and\neasy-to-use alternative. The tool includes a multiple choice exam sheet and\nworks with any scanner and printer.\n\nThis software and the\ncorresponding multiple choice sheet were developed as an independent study\nproject by Ian Sanders, a mechanical engineering student at the University of\nSouth Florida, under the direction of Dr. Autar Kaw.\n\nFor a detailed discussion of the algorithm and features in use, please\n[read the report](https://github.com/iansan5653/open-mcr-report/releases/tag/1.0.0)\nas submitted for the original independent study course.\n\n## Installation Instructions\n\nCurrently, packaged executables are only provided for Windows. For other operating\nsystems, see [Running From Source](#running-from-source--cli).\n\n### Windows Installation\n\nTo install the utility, simply download the latest `.exe` file from from the\n[releases](https://github.com/iansan5653/open-mcr/releases) page and\ninstall it. After installation, check your Start menu for a shortcut.\n\n### Running Without Install\n\nFor users who cannot or do not want to install the software on their machine,\nZIP file packages are also available for each [release](https://github.com/iansan5653/open-mcr/releases). Download the file,\nextract it anywhere on your machine, and run the `main.exe` file. This method\ndoes not require administrator priveleges.\n\n### Running From Source / CLI\n\nIf you wish to customize the software, use the command line interface, or run it\non a non-Windows device, you can run the Python program directly from the source files. This\nrequires Python and Pip to be installed on your machine.\n\n1. Clone the reposotory using Git, or download and extract the latest `Source code (zip)` file from\n  [releases](https://github.com/iansan5653/open-mcr/releases).\n2. Open a terminal / command prompt in the extracted directory.\n3. On Mac machines with fresh Python installations, you will to update TKinter from the default.\n4. Run `pip3 install -r requirements.txt` to install dependencies.\n7. Run `python3 src/main.py` for the CLI interface or `python3 src/main_gui.py` for the graphical interface.\n\n\u003e **Note**: On MacOS, if you see a black screen when running the GUI, you need to uninstall Python, install TKinter, and\n\u003e then reinstall Python. The easiest way to do this is to manage your installation with Homebrew as described [here](https://apple.stackexchange.com/a/315121).\n\n\u003e **Note**: On Linux machines, you may see an error message that `opencv` or `tkinter` are not found.\n\u003e If you see this, install those dependencies by running `sudo apt-get install python3-opencv python3-tk` and then try again.\n\n### Codespaces\n\nFor development, a pre-made environment is available in [Codespaces](https://github.com/features/codespaces):\n\n[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/iansan5653/open-mcr?quickstart=1)\n\n\u003e [!NOTE]\n\u003e The configuration auomatically installs the [`desktop-lite`](https://github.com/devcontainers/features/tree/main/src/desktop-lite)\n\u003e feature for running the GUI. This environment can be accessed in your browser through the forwarded `6080` port. The\n\u003e desktop password is `vscode`.\n\n## Printable Multiple Choice Sheet\n\nThe multiple choice sheet that must be used with this software is available\nfor printing here:\n\n* [75 Question Variant](https://github.com/iansan5653/open-mcr/raw/master/src/assets/multiple_choice_sheet_75q.pdf)\n* [150 Question Variant](https://github.com/iansan5653/open-mcr/raw/master/src/assets/multiple_choice_sheet_150q.pdf)\n\n## Usage Instructions\n\nRun the program by finding it in your Start menu after installing.\n\nFor full operating instructions, see the [Manual](src/assets/manual.md) or\nclick the \u003ckbd\u003eOpen Help\u003c/kbd\u003e button in the software.\n\n## Feedback / Bug Reports\n\nTo report a bug, request a new feature, or provide feedback, please\n[file an issue](https://github.com/iansan5653/open-mcr/issues/new).\n\n## License\n\n### Software License\n\nCopyright (C) 2019 Ian Sanders\n\nThis program is free software: you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation, either version 3 of the License, or\n(at your option) any later version.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\nGNU General Public License for more details.\n\nFor the full license text, see [license.txt](./license.txt).\n\n### Multiple Choice Sheet License\n\nThe multiple choice sheet distributed with this software is licensed under the\nCreative Commons Attribution-NonCommercial-ShareAlike 4.0 International license\n(CC BY-NC-SA 4.0). In summary, this means that you are free to distribute and\nmodify the document so long as you share it under the same license, provide\nattribution, and do not use it for commercial purposes. For the full license,\nsee\n[the Creative Commons website](https://creativecommons.org/licenses/by-nc-sa/4.0/).\n\n**Note**: You are explicitly _allowed_ to distribute the multiple choice sheet\nwithout attribution if using it unmodified for educational purpose and not\nin any way implying that it is your own work. This is an exception to the\nCreative Commons terms. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiansan5653%2Fopen-mcr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiansan5653%2Fopen-mcr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiansan5653%2Fopen-mcr/lists"}