{"id":15020368,"url":"https://github.com/sivakumar-mahalingam/fastmrz","last_synced_at":"2025-09-10T00:44:00.530Z","repository":{"id":228179525,"uuid":"773325166","full_name":"sivakumar-mahalingam/fastmrz","owner":"sivakumar-mahalingam","description":"⚡Extracting the Machine Readable Zone (MRZ) from passport or any document images","archived":false,"fork":false,"pushed_at":"2025-03-07T14:38:57.000Z","size":70975,"stargazers_count":59,"open_issues_count":4,"forks_count":13,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-29T19:01:26.370Z","etag":null,"topics":["identity-document","mrz","mrz-scanner","ocr","opencv","opencv-python","passport","passport-mrz","python","tesseract","tesseract-ocr","text-recognition"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/fastmrz","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sivakumar-mahalingam.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2024-03-17T11:13:21.000Z","updated_at":"2025-03-29T08:58:37.000Z","dependencies_parsed_at":"2024-09-22T23:31:43.545Z","dependency_job_id":"7dfb9061-c00d-4021-8609-266541c91f6c","html_url":"https://github.com/sivakumar-mahalingam/fastmrz","commit_stats":{"total_commits":95,"total_committers":4,"mean_commits":23.75,"dds":0.368421052631579,"last_synced_commit":"68d2492a18e751c2e733bc7252154144e771e5c9"},"previous_names":["sivakumar-mahalingam/passport-mrz-reader","sivakumar-mahalingam/laghima"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sivakumar-mahalingam%2Ffastmrz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sivakumar-mahalingam%2Ffastmrz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sivakumar-mahalingam%2Ffastmrz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sivakumar-mahalingam%2Ffastmrz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sivakumar-mahalingam","download_url":"https://codeload.github.com/sivakumar-mahalingam/fastmrz/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247393547,"owners_count":20931811,"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":["identity-document","mrz","mrz-scanner","ocr","opencv","opencv-python","passport","passport-mrz","python","tesseract","tesseract-ocr","text-recognition"],"created_at":"2024-09-24T19:54:58.520Z","updated_at":"2025-04-05T20:03:06.749Z","avatar_url":"https://github.com/sivakumar-mahalingam.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Fast MRZ\n\n\u003cdiv align=\"center\"\u003e\n\n[![License](https://img.shields.io/badge/license-AGPL%203.0-34D058?color=blue)](https://github.com/sivakumar-mahalingam/fastmrz/blob/main/LICENSE)\n[![Downloads](https://static.pepy.tech/badge/fastmrz)](https://pypistats.org/packages/fastmrz)\n![Python](https://img.shields.io/badge/python-3.8+-blue?logo=python\u0026logoColor=959DA5)\n[![CodeQL](https://github.com/sivakumar-mahalingam/fastmrz/actions/workflows/codeql.yml/badge.svg)](https://github.com/sivakumar-mahalingam/fastmrz/actions/workflows/codeql.yml)\n[![PyPI](https://img.shields.io/pypi/v/fastmrz.svg?logo=pypi\u0026logoColor=959DA5\u0026color=blue)](https://pypi.org/project/fastmrz/)\n\n\u003ca href=\"https://github.com/sivakumar-mahalingam/fastmrz/\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/sivakumar-mahalingam/fastmrz/main/docs/FastMRZ.png\" target=\"_blank\" /\u003e\n\u003c/a\u003e\n\nFastMRZ is an open-source Python package that extracts the Machine Readable Zone (MRZ) from passports and other documents. FastMRZ accepts various input formats such as Image, Base64 string, MRZ string, or NumPy array. \n\n[Features](#features) •\n[Built With](#built-with) •\n[Prerequisites](#prerequisites) •\n[Installation](#installation) •\n[Example](#example) •\n[Wiki](#wiki) •\n[ToDo](#todo) •\n[Contributing](#contributing)\n\n\u003c/div\u003e\n\n## ️✨Features\n\n- 👁️Detects and extracts the MRZ region from document images\n- ️🔍Contour detection to accurately identify the MRZ area\n- 🎨Custom trained models using ONNX \n- 🆗Contains checksum logics for data validation\n- 📤Outputs the extracted MRZ region as text/json\n\n\n## 🛠️Built With\n\n![OpenCV](https://img.shields.io/badge/OpenCV-27338e?style=for-the-badge\u0026logo=OpenCV\u0026logoColor=white)\n![Tesseract OCR](https://img.shields.io/badge/Tesseract%20OCR-0F9D58?style=for-the-badge\u0026logo=google\u0026logoColor=white)\n![NumPy](https://img.shields.io/badge/numpy-316192?style=for-the-badge\u0026logo=numpy\u0026logoColor=white)\n![ONNX](https://img.shields.io/badge/ONNX-7B7B7B?style=for-the-badge\u0026logo=onnx\u0026logoColor=white)\n\n## 🚨Prerequisites\n- Install [Tesseract OCR](https://tesseract-ocr.github.io/tessdoc/Installation.html) engine. And set `PATH` variable with the executable and ensure that tesseract can be reached from the command line. \n\n## ⚙️Installation\n\n1. Install `fastmrz`\n    ```bash\n    pip install fastmrz\n    ```\n   This can be done through conda too if you prefer.\n\n     ```bash\n     conda create -n fastmrz tesseract -c conda-forge\n     conda activate fastmrz\n     ```\n\n2. Copy  the `mrz.traineddata` file from the `tessdata` folder of the [repository](https://github.com/sivakumar-mahalingam/fastmrz/raw/main/tessdata/mrz.traineddata) into the `tessdata` folder of the Tesseract installation on **YOUR MACHINE**\n\n## 💡Example\n\n```Python\nfrom fastmrz import FastMRZ\nimport json\n\nfast_mrz = FastMRZ()\n# Pass file path of installed Tesseract OCR, incase if not added to PATH variable\n# fast_mrz = FastMRZ(tesseract_path=r'/opt/homebrew/Cellar/tesseract/5.3.4_1/bin/tesseract') # Default path in Mac\n# fast_mrz = FastMRZ(tesseract_path=r'C:\\\\Program Files\\\\Tesseract-OCR\\\\tesseract.exe') # Default path in Windows\npassport_mrz = fast_mrz.get_details(\"../data/passport_uk.jpg\", include_checkdigit=False)\nprint(\"JSON:\")\nprint(json.dumps(passport_mrz, indent=4))\n\nprint(\"\\n\")\n\npassport_mrz = fast_mrz.get_details(\"../data/passport_uk.jpg\", ignore_parse=True)\nprint(\"TEXT:\")\nprint(passport_mrz)\n```\n\n**OUTPUT:**\n```Console\nJSON:\n{\n    \"mrz_type\": \"TD3\",\n    \"document_code\": \"P\",\n    \"issuer_code\": \"GBR\",\n    \"surname\": \"PUDARSAN\",\n    \"given_name\": \"HENERT\",\n    \"document_number\": \"707797979\",\n    \"document_number_checkdigit\": \"2\",\n    \"nationality_code\": \"GBR\",\n    \"birth_date\": \"1995-05-20\",\n    \"sex\": \"M\",\n    \"expiry_date\": \"2017-04-22\",\n    \"optional_data\": \"\",\n    \"mrz_text\": \"P\u003cGBRPUDARSAN\u003c\u003cHENERT\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\\n7077979792GBR9505209M1704224\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c00\",\n    \"status\": \"SUCCESS\"\n}\n\n\nTEXT:\nP\u003cGBRPUDARSAN\u003c\u003cHENERT\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\n7077979792GBR9505209M1704224\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c\u003c00\n```\n\n## 📃Wiki\n\n\u003cdetails\u003e\n    \u003csummary\u003e\u003cb\u003eMRZ Types \u0026 Format\u003c/b\u003e\u003c/summary\u003e\n\nThe standard for MRZ code is strictly regulated and has to comply with [Doc 9303](https://www.icao.int/publications/pages/publication.aspx?docnum=9303). Machine Readable Travel Documents published by the International Civil Aviation Organization.\n\nThere are currently several types of ICAO standard machine-readable zones, which vary in the number of lines and characters in each line:\n\n- TD-1 (e.g. citizen’s identification card, EU ID card, US Green Card): consists of 3 lines, 30 characters each.\n- TD-2 (e.g. Romania ID, old type of German ID), and MRV-B (machine-readable visas type B — e.g. Schengen visa): consists of 2 lines, 36 characters each.\n- TD-3 (all international passports, also known as MRP), and MRV-A (machine-readable visas type A — issued by the USA, Japan, China, and others): consist of 2 lines, 44 characters each.\n\nNow, based on the example of a national passport, let us take a closer look at the MRZ composition.\n\n![MRZ fields distribution](https://raw.githubusercontent.com/sivakumar-mahalingam/fastmrz/main/docs/mrz_fields_distribution.png)\n\n\u003c/details\u003e\n\n![MRZ GIF](https://raw.githubusercontent.com/sivakumar-mahalingam/fastmrz/main/docs/mrz.gif)\n\n## ✅ToDo\n\n- [x] Include mrva and mrvb documents\n- [x] Add wiki page\n- [x] Support numpy array as input\n- [x] Support mrz text as input\n- [x] Support base64 as input\n- [ ] Support pdf as input\n- [x] Function to return mrz text as output\n- [ ] Bulk process\n- [ ] Add function parameter - Image Enhancement Model\n- [ ] Add function parameter - Text Image Enhancement Model\n- [ ] Train Tesseract model with additional data\n- [x] Add function parameter - include_checkdigit\n- [ ] Add function - get_mrz_image\n- [x] Add function - validate_mrz\n- [ ] Add function - generate_mrz\n- [ ] Extract face image\n- [ ] Add documentation page\n- [ ] Add all checkdigit status\n\n## 🤝 Contributing\n\nContributions are welcome! Here's how you can help:\n\n1. Fork the repository\n2. Create a new branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Commit your changes (`git commit -m 'feat: add amazing feature'`)\n5. Push to the branch (`git push origin feature/amazing-feature`)\n6. Open a Pull Request\n\n## ⚖️License\n\nDistributed under the AGPL-3.0 License. See `LICENSE` for more information.\n\n## 🙏Show your support\n\nGive a ⭐️ if \u003ca href=\"https://github.com/sivakumar-mahalingam/fastmrz/\"\u003ethis\u003c/a\u003e project helped you!\n\n## 🚀Who's Using It?\n\nWe’d love to know who’s using **fastmrz**! If your company or project uses this package, feel free to share your story. You can:\n\n- Open an issue with the title \"We are using fastmrz!\" and include your project or company name.\n\nThank you for supporting **fastmrz**! 🤟\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsivakumar-mahalingam%2Ffastmrz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsivakumar-mahalingam%2Ffastmrz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsivakumar-mahalingam%2Ffastmrz/lists"}