{"_id":"@armghan3071/omrchecker","_rev":"3-762acbce71153850f3d8f8b68e56f79f","name":"@armghan3071/omrchecker","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.0":{"name":"@armghan3071/omrchecker","version":"1.0.0","keywords":[],"author":"","license":"ISC","_id":"@armghan3071/omrchecker@1.0.0","maintainers":[{"name":"armghan3071","email":"armghan3071@gmail.com"}],"homepage":"https://github.com/armghan3071/omrchecker#readme","bugs":{"url":"https://github.com/armghan3071/omrchecker/issues"},"dist":{"shasum":"f976b1c4a47252d0316c175e36e19d53be0c37e3","tarball":"https://registry.npmjs.org/@armghan3071/omrchecker/-/omrchecker-1.0.0.tgz","fileCount":5,"integrity":"sha512-euXLIELd5/qBRbPgxCQo1ZKJtSYkm+9Yv3eaZbNDLWDrm4bsolKkfi7I4S9xfJCyDkR41V8bnEC4gtG6jTia1w==","signatures":[{"sig":"MEUCIQDo5ZWkMsPUJr2wizByu1er8uf1YICRg8/8rT3QWAA3zgIgI3CuQv961ZuObCC9czhtRW4hHi9KMtWbMZ4YigLB+Tc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":21664731},"main":"./dist/omr-checker.umd.cjs","type":"module","module":"./dist/omr-checker.js","exports":{".":{"import":"./dist/omr-checker.js","require":"./dist/omr-checker.umd.cjs"},"./app":"./dist/omr-checker.js","./app.js":"./dist/omr-checker.js"},"gitHead":"c180d741fa10fbba2e846328a9a546e203c2bbef","scripts":{"dev":"vite","build":"vite build"},"_npmUser":{"name":"armghan3071","email":"armghan3071@gmail.com"},"repository":{"url":"git+https://github.com/armghan3071/omrchecker.git","type":"git"},"_npmVersion":"11.8.0","description":"High-performance client-side OMR engine using OpenCV.js","directories":{},"_nodeVersion":"22.21.1","dependencies":{"@techstark/opencv-js":"^4.12.0-release.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vite":"^7.3.1","vite-plugin-webworker-service":"^1.1.0"},"_npmOperationalInternal":{"tmp":"tmp/omrchecker_1.0.0_1770648130597_0.7458354606921052","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@armghan3071/omrchecker","version":"1.0.1","keywords":[],"author":"","license":"ISC","_id":"@armghan3071/omrchecker@1.0.1","maintainers":[{"name":"armghan3071","email":"armghan3071@gmail.com"}],"homepage":"https://github.com/armghan3071/omrchecker#readme","bugs":{"url":"https://github.com/armghan3071/omrchecker/issues"},"dist":{"shasum":"f704c19e653752e39dfd25b7e3c6eb042814a08b","tarball":"https://registry.npmjs.org/@armghan3071/omrchecker/-/omrchecker-1.0.1.tgz","fileCount":5,"integrity":"sha512-QrseW/Vqr9f0pmlADD+K+CpD51pJx6H96NvTb8b0c8zmwR0HpIvE3wrzIDcKI3q2w6ZMJscAsinHt4h+QxGa/A==","signatures":[{"sig":"MEUCICkEIoQafj49QFg05Fg+uKWQ7xX+bZ5k61YcXHBDQ5mSAiEAoFnJbZevhA9rlR5JcG19SO7HZ/qyHmEqfhVsxyDCEho=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":83861},"main":"./dist/omr-checker.umd.cjs","type":"module","module":"./dist/omr-checker.js","exports":{".":{"import":"./dist/omr-checker.js","require":"./dist/omr-checker.umd.cjs"},"./app":"./dist/omr-checker.js","./app.js":"./dist/omr-checker.js"},"gitHead":"2c8cf119157ff4d32c107f42d444423083482a20","scripts":{"dev":"vite","build":"vite build"},"_npmUser":{"name":"armghan3071","email":"armghan3071@gmail.com"},"repository":{"url":"git+https://github.com/armghan3071/omrchecker.git","type":"git"},"_npmVersion":"11.8.0","description":"High-performance client-side OMR engine using OpenCV.js","directories":{},"_nodeVersion":"22.21.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vite":"^7.3.1","vite-plugin-webworker-service":"^1.1.0"},"_npmOperationalInternal":{"tmp":"tmp/omrchecker_1.0.1_1770734158969_0.6203633585760944","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@armghan3071/omrchecker","version":"1.0.2","description":"High-performance client-side OMR engine using OpenCV.js","repository":{"type":"git","url":"git+https://github.com/armghan3071/omrchecker.git"},"bugs":{"url":"https://github.com/armghan3071/omrchecker/issues"},"homepage":"https://github.com/armghan3071/omrchecker#readme","publishConfig":{"access":"public"},"main":"./dist/omr-checker.umd.cjs","module":"./dist/omr-checker.js","exports":{".":{"import":"./dist/omr-checker.js","require":"./dist/omr-checker.umd.cjs"},"./app":"./dist/omr-checker.js","./app.js":"./dist/omr-checker.js"},"scripts":{"dev":"vite","build":"vite build"},"keywords":[],"author":"","license":"ISC","type":"module","devDependencies":{"vite":"^7.3.1","vite-plugin-webworker-service":"^1.1.0"},"gitHead":"54d909bf6dde7bc8c3297c9f844df32097564209","_id":"@armghan3071/omrchecker@1.0.2","_nodeVersion":"22.21.1","_npmVersion":"11.8.0","dist":{"integrity":"sha512-3qB1fhEp+xQNILx8kRXTHfCzaUJuV1VbsXUd+5DCuvzLbCuR9cNwiC0/K/N0YbbqKFCmSMACfE5Qq7kc5WUAUg==","shasum":"8872123a566ea1292380919f713ebb2410bbe65b","tarball":"https://registry.npmjs.org/@armghan3071/omrchecker/-/omrchecker-1.0.2.tgz","fileCount":5,"unpackedSize":83013,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDN16QfQKhQb5TAeh55oYWWwP2Vf8fzDCMuMZwhOxvgsQIgQpxYrNnPbFYmSF2A378yqI0NbrrkqPjL7uixsYR9GGs="}]},"_npmUser":{"name":"armghan3071","email":"armghan3071@gmail.com"},"directories":{},"maintainers":[{"name":"armghan3071","email":"armghan3071@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/omrchecker_1.0.2_1770740846090_0.740389146981568"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-09T14:42:10.477Z","modified":"2026-02-10T16:27:26.373Z","1.0.0":"2026-02-09T14:42:10.964Z","1.0.1":"2026-02-10T14:35:59.115Z","1.0.2":"2026-02-10T16:27:26.252Z"},"bugs":{"url":"https://github.com/armghan3071/omrchecker/issues"},"license":"ISC","homepage":"https://github.com/armghan3071/omrchecker#readme","keywords":[],"repository":{"type":"git","url":"git+https://github.com/armghan3071/omrchecker.git"},"description":"High-performance client-side OMR engine using OpenCV.js","maintainers":[{"name":"armghan3071","email":"armghan3071@gmail.com"}],"readme":"# OMR Checker Library\r\n\r\nA powerful, client-side Optical Mark Recognition (OMR) engine for JavaScript. Process bubble sheets, exams, and surveys entirely in the browser using OpenCV and Web Workers.\r\n\r\n### Features\r\n\r\n- 🚀 **Client-Side Processing:** No server required. All image processing happens locally.\r\n- ⚡ **Non-Blocking:** Uses a dedicated Web Worker to keep your UI responsive.\r\n- 🎯 **High Accuracy:** Algorithms for rotation correction and perspective warping.\r\n- 📄 **Batch Support:** Process hundreds of images in a single loop.\r\n- 🛠 **Layout Debugging:** Built-in tools to visualize grid alignment.\r\n\r\n### Installation\r\n\r\n```sh\r\nnpm install @armghan3071/omrchecker\r\n```\r\n\r\n#### Vanilla JS Example\r\n\r\n```javascript\r\nimport { OMRChecker } from '@armghan3071/omrchecker';\r\n\r\nconst engine = new OMRChecker();\r\n\r\ndocument.getElementById('scanBtn').addEventListener('click', async () => {\r\n  const fileInput = document.getElementById('fileInput');\r\n  const files = Array.from(fileInput.files);\r\n  \r\n  // Load Template & Marker\r\n  const template = { ... }; // Your JSON object\r\n  const marker = await fetch('marker.jpg').then(res => res.blob());\r\n\r\n  const results = await engine.process(files, template, marker);\r\n  console.log(results);\r\n});\r\n```\r\n\r\n### API Reference\r\n\r\n#### `new OMRChecker(config = {})`\r\n- **config** `(Object)`: Optional configuration object.\r\n    - `cv`: If you are using Open CV in your existing project\r\n    - `includeOutputImages:`: True if you want to include markedImage during grading section\r\n\r\n#### `async process(files, template, marker, setLayout)`\r\n- **files** `(File[])`: Array of browser `File` objects (images).\r\n- **template** `(Object)`: The JSON template object defining bubble positions.\r\n- **marker** `(Blob|File)`: The image file used for alignment markers (must match the visual marker on the paper).\r\n- **setLayout** `(Boolean)`: \r\n    - `false` (default): Returns CSV grading results.\r\n    - `true`: Returns images with grid overlays (useful for debugging layouts).\r\n\r\n#### `terminate()`\r\n- Instantly kills the background worker and frees memory. Call this when the component is destroyed.\r\n\r\n### Configuration\r\n\r\nThe `template.json` defines where the engine should look for bubbles.\r\n\r\n```json\r\n{\r\n  \"pageDimensions\": [\r\n    1189,\r\n    1682\r\n  ],\r\n  \"bubbleDimensions\": [\r\n    30,\r\n    30\r\n  ],\r\n  \"preProcessors\": [\r\n    {\r\n      \"name\": \"CropPage\",\r\n      \"options\": {\r\n        \"morphKernel\": [\r\n          10,\r\n          10\r\n        ]\r\n      }\r\n    },\r\n    {\r\n  \"name\": \"CropOnMarkers\",\r\n  \"options\": {\r\n    \"relativePath\": \"omr_marker.jpg\",\r\n    \"sheetToMarkerWidthRatio\": 17,     \r\n    \"min_matching_threshold\": 0.3,\r\n    \"marker_rescale_range\": [20, 100]      \r\n  }\r\n}\r\n  ],\r\n  \"fieldBlocks\": {\r\n    \"MCQBlock1\": {\r\n      \"fieldType\": \"QTYPE_MCQ4\",\r\n      \"origin\": [\r\n        134,\r\n        684\r\n      ],\r\n      \"fieldLabels\": [\r\n        \"q1..11\"\r\n      ],\r\n      \"bubblesGap\": 79,\r\n      \"labelsGap\": 62\r\n    }\r\n  }\r\n}\r\n\r\n```\r\n\r\n### Credits & References\r\n\r\nThis project is a JavaScript adaptation and port of the original [OMRChecker](https://github.com/Udayraj123/OMRChecker) by Udayraj123. It brings the robust grading logic of the Python-based engine directly to the web for high-performance, client-side processing.\r\n\r\nThe development and technical architecture of this library were made possible through:\r\n\r\n* **Primary Logic Source:** Inspired by the Python OMR system developed by [Udayraj123](https://github.com/Udayraj123/OMRChecker), leveraging his research into rotation, perspective correction, and grid-based bubble detection.\r\n* **Core Image Engine:** Powered by [OpenCV.js](https://docs.opencv.org/4.x/d5/d10/tutorial_js_root.html), the official JavaScript port of the Open Source Computer Vision Library.\r\n* **AI Collaboration:** This project was architected, debugged, and documented with the strategic assistance of **Gemini 3 Pro**. The AI code assistant played a critical role in optimizing Web Worker communication, resolving complex Vite/Webpack bundling issues, and implementing minification-safe class structures.\r\n\r\n### License\r\n\r\nMIT","readmeFilename":"README.md"}