# Apple Vision Framework Python Utilities
Fast and accurate OCR on images and PDFs using Apple Vision framework (`pyobjc-framework-Vision`) directly from command line.
- [Apple Vision Framework Python Utilities](#apple-vision-framework-python-utilities)
- [Features](#features)
- [Demo](#demo)
- [Installation](#installation)
- [pipx](#pipx)
- [pip](#pip)
- [Usage](#usage)
- [Develop](#develop)
- [Test](#test)
## Features
- Fast and accurate, multi-language support (`-l`, `--lang`), powered by Apple's industry-strength Vision framework (`pyobjc-framework-Vision`).
- Supports all common input image formats: PNG, JPEG, TIFF and WebP.
- Supports PDF input (the file gets converted to images first). This tool does NOT assume a file is PDF just because it has a `.pdf` extension, you need to pass `-p`, `--pdf` flag.
- Outputs extracted text only by default, but can output in JSON format containing confidence of recognition for each line with `-j`, `--json` flag.
## Demo
Below is the output of running the [tests](#test):
https://g.teddysc.me/96d5b1217b90035c163b3c97ce99112f
## Installation
Requires Python >= 3.11, <4.0.
Since this package uses Apple's Vision framework, it only works on macOS.
To OCR PDFs with `-p`, you need to install required dependency `poppler` with `brew install poppler` ([detailed guide](https://github.com/Belval/pdf2image)).
### pipx
This is the recommended installation method.
```
$ pipx install apple-vision-utils
```
### [pip](https://pypi.org/project/apple-vision-utils/)
```
$ pip install apple-vision-utils
```
## Usage
```
$ apple-ocr --help
usage: apple-ocr [-h] [-j] [-p] [-l LANG] [--pdf2image-only]
[--pdf2image-dir PDF2IMAGE_DIR] [-V]
file_path
Extract text from an image or PDF using Apple's Vision framework.
positional arguments:
file_path Path to the image or PDF file.
options:
-h, --help show this help message and exit
-j, --json Output results in JSON format.
-p, --pdf Specify if the input file is a PDF.
-l LANG, --lang LANG Specify the language for text recognition (e.g., eng,
fra, deu, zh-Hans for Simplified Chinese, zh-Hant for
Traditional Chinese). Default is 'zh-Hant', which
works with images containing both Chinese characters
and latin letters.
--pdf2image-only Only convert PDF to images without performing OCR.
--pdf2image-dir PDF2IMAGE_DIR
Specify the directory to store output images. By
default, a secure temporary directory is created.
-V, --version show program's version number and exit
```
## Develop
```
$ git clone https://github.com/tddschn/apple-vision-utils.git
$ cd apple-vision-utils
$ poetry install
```
## Test
```
# in the root of the project
poetry install
poetry shell
cd tests && ./test.sh
```
Raw data
{
"_id": null,
"home_page": "https://github.com/tddschn/apple-vision-utils",
"name": "apple-vision-utils",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": null,
"keywords": "ocr, apple-vision-framework",
"author": "Teddy Xinyuan Chen",
"author_email": "45612704+tddschn@users.noreply.github.com",
"download_url": "https://files.pythonhosted.org/packages/e1/f1/64558aebfdbff53932be8557ea0afb4b454d2c0a8f7bed809313c866b4db/apple_vision_utils-0.1.6.tar.gz",
"platform": null,
"description": "# Apple Vision Framework Python Utilities\n\nFast and accurate OCR on images and PDFs using Apple Vision framework (`pyobjc-framework-Vision`) directly from command line.\n\n- [Apple Vision Framework Python Utilities](#apple-vision-framework-python-utilities)\n - [Features](#features)\n - [Demo](#demo)\n - [Installation](#installation)\n - [pipx](#pipx)\n - [pip](#pip)\n - [Usage](#usage)\n - [Develop](#develop)\n - [Test](#test)\n\n## Features\n\n- Fast and accurate, multi-language support (`-l`, `--lang`), powered by Apple's industry-strength Vision framework (`pyobjc-framework-Vision`).\n- Supports all common input image formats: PNG, JPEG, TIFF and WebP.\n- Supports PDF input (the file gets converted to images first). This tool does NOT assume a file is PDF just because it has a `.pdf` extension, you need to pass `-p`, `--pdf` flag.\n- Outputs extracted text only by default, but can output in JSON format containing confidence of recognition for each line with `-j`, `--json` flag.\n\n\n## Demo\n\nBelow is the output of running the [tests](#test):\n\nhttps://g.teddysc.me/96d5b1217b90035c163b3c97ce99112f\n\n## Installation\n\nRequires Python >= 3.11, <4.0.\n\nSince this package uses Apple's Vision framework, it only works on macOS.\n\nTo OCR PDFs with `-p`, you need to install required dependency `poppler` with `brew install poppler` ([detailed guide](https://github.com/Belval/pdf2image)).\n\n### pipx\n\nThis is the recommended installation method.\n\n```\n$ pipx install apple-vision-utils\n```\n\n### [pip](https://pypi.org/project/apple-vision-utils/)\n\n```\n$ pip install apple-vision-utils\n```\n\n## Usage\n\n```\n$ apple-ocr --help\n\nusage: apple-ocr [-h] [-j] [-p] [-l LANG] [--pdf2image-only]\n [--pdf2image-dir PDF2IMAGE_DIR] [-V]\n file_path\n\nExtract text from an image or PDF using Apple's Vision framework.\n\npositional arguments:\n file_path Path to the image or PDF file.\n\noptions:\n -h, --help show this help message and exit\n -j, --json Output results in JSON format.\n -p, --pdf Specify if the input file is a PDF.\n -l LANG, --lang LANG Specify the language for text recognition (e.g., eng,\n fra, deu, zh-Hans for Simplified Chinese, zh-Hant for\n Traditional Chinese). Default is 'zh-Hant', which\n works with images containing both Chinese characters\n and latin letters.\n --pdf2image-only Only convert PDF to images without performing OCR.\n --pdf2image-dir PDF2IMAGE_DIR\n Specify the directory to store output images. By\n default, a secure temporary directory is created.\n -V, --version show program's version number and exit\n```\n\n\n## Develop\n\n```\n$ git clone https://github.com/tddschn/apple-vision-utils.git\n$ cd apple-vision-utils\n$ poetry install\n```\n\n## Test\n\n```\n# in the root of the project\npoetry install\npoetry shell\ncd tests && ./test.sh\n```",
"bugtrack_url": null,
"license": "MIT",
"summary": "Fast and accurate OCR on images and PDFs using Apple Vision framework directly from command line.",
"version": "0.1.6",
"project_urls": {
"Bug Tracker": "https://github.com/tddschn/apple-vision-utils/issues",
"Homepage": "https://github.com/tddschn/apple-vision-utils",
"Repository": "https://github.com/tddschn/apple-vision-utils"
},
"split_keywords": [
"ocr",
" apple-vision-framework"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2cd59d22157e0590330aa43a45a5c2496fa59c582b1775c69aed16c80c1aa5b3",
"md5": "f9ea7e66d6ef2897f2d026abab912cc1",
"sha256": "45d57f9b4525657be16be70e3feb63bed7c9ee31bf2b2a7149bd90caa2de3c74"
},
"downloads": -1,
"filename": "apple_vision_utils-0.1.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f9ea7e66d6ef2897f2d026abab912cc1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 5592,
"upload_time": "2024-05-21T17:42:35",
"upload_time_iso_8601": "2024-05-21T17:42:35.354016Z",
"url": "https://files.pythonhosted.org/packages/2c/d5/9d22157e0590330aa43a45a5c2496fa59c582b1775c69aed16c80c1aa5b3/apple_vision_utils-0.1.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e1f164558aebfdbff53932be8557ea0afb4b454d2c0a8f7bed809313c866b4db",
"md5": "8c3bad47a3ed3a2f970bdb2678b85f1a",
"sha256": "836c20f52f32a93b74d33298f47ca06f50dc43814a5f978ce24d3ad32e335d38"
},
"downloads": -1,
"filename": "apple_vision_utils-0.1.6.tar.gz",
"has_sig": false,
"md5_digest": "8c3bad47a3ed3a2f970bdb2678b85f1a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 4431,
"upload_time": "2024-05-21T17:42:36",
"upload_time_iso_8601": "2024-05-21T17:42:36.343339Z",
"url": "https://files.pythonhosted.org/packages/e1/f1/64558aebfdbff53932be8557ea0afb4b454d2c0a8f7bed809313c866b4db/apple_vision_utils-0.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-21 17:42:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tddschn",
"github_project": "apple-vision-utils",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "apple-vision-utils"
}
JSON
