ocrmac Documentation

On macOS Sonoma and later, you can use the livetext framework, which is more powerful than the standard vision backend.

Key differences when using livetext:

• recognition_level and confidence_threshold are not available.
• The confidence output is always 1.
• Supports a unit parameter: use unit='line' to return full-line items instead of token-level items.

You can access LiveText via the OCR class or a direct helper function.

from ocrmac import ocrmac

# Using the OCR class
annotations = ocrmac.OCR('test.png', framework="livetext", unit='line').recognize()

# Using the helper directly
annotations = ocrmac.livetext_from_image('test.png')

The preferred method to install ocrmac is using pip, which ensures you receive the most recent stable release.

Run the following command in your terminal:

$ pip install ocrmac

Install the ocrmac package using pip. Note that this library only works on macOS systems (version 10.15 or newer) as it utilizes Apple's Vision framework.

pip install ocrmac

To use ocrmac in your Python project, ensure it is installed in your environment and then import the package directly.

import ocrmac

If you need to install from source, you can either clone the repository or download the tarball, then use setup.py to install.

1. Clone the repository:

$ git clone git://github.com/straussmaximilian/ocrmac

2. Or download the tarball:

$ curl -OJL https://github.com/straussmaximilian/ocrmac/tarball/master

3. Install using setup.py: Once you have the source files locally, run:

$ python setup.py install

If OCR output changes due to macOS updates or transitions between Apple Silicon generations, you may need to regenerate the reference images used by the test suite. This is done by running the ocrmac.OCR class with different recognition_level or framework settings on a source image and saving the annotated results.

To verify the process, you can run the test suite using pytest after regeneration.

pytest tests/test_ocrmac.py -v

Use the ocrmac.OCR class to extract text from an image file path or a PIL image object. Calling .recognize() returns a list of tuples containing the extracted text, its confidence score, and its bounding box.

from ocrmac import ocrmac
annotations = ocrmac.OCR('test.png').recognize()
print(annotations)

You can visualize the OCR results by generating annotated images. Use .annotate_PIL() to return a PIL image or .annotate_matplotlib() to return a matplotlib figure.

from ocrmac import ocrmac
ocrmac.OCR('test.png').annotate_PIL()

When initializing the ocrmac.OCR class, you can pass several arguments to fine-tune the extraction:

• recognition_level: Set to 'fast' or 'accurate'.
• language_preference: A list of language codes (e.g., ['en-US', 'zh-Hans']) used for post-processing. Use IANA language subtags.

Note: The recognition_level affects which languages are available (the 'fast' level has fewer supported languages).

ocrmac.OCR('test.png', recognition_level='accurate', language_preference=['en-US'])

The library supports two primary backends for text extraction:

• vision: The standard Apple Vision framework.
• livetext: The newer, stronger framework available on macOS Sonoma+.

To visualize the OCR results directly on the image, use the .annotate_PIL() method. This returns a PIL (Python Imaging Library) image object with the recognized text overlaid or highlighted.

from ocrmac import ocrmac

# Create an annotated PIL image with a specific language preference
img = ocrmac.OCR('test.png', language_preference=['en-US']).annotate_PIL()
img

Use the ocrmac.OCR class with recognition_level="accurate" to generate images optimized for precision. This is useful for creating reference images for high-accuracy OCR tasks.

Key parameters:

• recognition_level: Set to "accurate".
• language_preference: A list of language strings (e.g., ['en-US']).
• confidence_threshold: A float (e.g., 1.0).
• .annotate_PIL(): Returns a PIL Image object with OCR annotations overlaid.

img_accurate = ocrmac.OCR(
    SOURCE_IMAGE, 
    recognition_level="accurate", 
    language_preference=['en-US'],
    confidence_threshold=1.0
).annotate_PIL()

img_accurate.save(OUTPUT_ACCURATE, format="png")