ocrbridge-ocrmac is an OCR Bridge engine backed by Apple's Vision framework via ocrmac.
This package plugs into OCR Bridge through Python entry points and provides HOCR output for images and PDFs on macOS.
Entry point registration (from pyproject.toml):
[project.entry-points."ocrbridge.engines"]
ocrmac = "ocrbridge.engines.ocrmac:OcrmacEngine"- Native Apple OCR via Vision framework
- LiveText mode support on newer macOS versions
- Input formats: JPEG, PNG, TIFF, PDF
- HOCR XML output with bbox and confidence metadata
- Automatic plugin discovery in OCR Bridge
- macOS only (runtime enforces
Darwin) - macOS 10.15+ for Vision modes (
fast,balanced,accurate) - macOS 14.0+ for
livetext
This package will not run on Linux or Windows.
pip install ocrbridge-ocrmacCompatibility quick check:
- Python
>=3.10 - macOS
>=10.15(>=14.0forlivetext) - Key runtime deps:
ocrbridge-core>=3.1.0,ocrmac>=0.2.2
The engine is discovered automatically by OCR Bridge, or you can import and use it directly.
Stable imports from this package:
OcrmacEngineOcrmacParamsRecognitionLevel
languages(list[str] | None): IETF BCP 47 codes (for example"en-US","zh-Hans")recognition_level(RecognitionLevel):fast,balanced,accurate,livetext
Defaults:
languages=None(auto-detect)recognition_level=RecognitionLevel.BALANCED
from pathlib import Path
from ocrbridge.engines.ocrmac import OcrmacEngine, OcrmacParams, RecognitionLevel
engine = OcrmacEngine()
# Process with defaults
hocr = engine.process(Path("document.pdf"))
# Process with custom parameters
params = OcrmacParams(
languages=["en-US", "fr-FR"],
recognition_level=RecognitionLevel.ACCURATE,
)
hocr = engine.process(Path("document.pdf"), params)
# LiveText (requires macOS 14+)
params_livetext = OcrmacParams(
languages=["en-US"],
recognition_level=RecognitionLevel.LIVETEXT,
)
hocr = engine.process(Path("document.pdf"), params_livetext)This package exposes one OCR Bridge engine entry point:
- Group:
ocrbridge.engines - Name:
ocrmac - Target:
ocrbridge.engines.ocrmac:OcrmacEngine
If the package is installed but not discovered, run:
from importlib.metadata import entry_points
eps = entry_points()
group = "ocrbridge.engines"
if hasattr(eps, "select"):
engines = eps.select(group=group)
else:
engines = eps.get(group, [])
for ep in engines:
print(f"{ep.name} -> {ep.value}").jpg.jpeg.png.pdf.tiff.tif
This repository uses uv for Python environments/dependencies and mise for task aliases.
mise run installmise run lint
mise run format
mise run typecheck
mise run test
mise run check
mise run allDirect equivalents:
uv sync --extra dev
uv run ruff check src tests
uv run ruff format src tests
uv run pyright
uv run pytestUse pytest node IDs:
uv run pytest tests/test_models.py::TestOcrmacParams::test_validate_languages
uv run pytest tests/test_engine_unit.py::TestProcessMethod::test_process_routes_to_pdf_handlerUseful filters:
uv run pytest tests/test_engine_integration.py -m integration
uv run pytest -k livetext- Output is HOCR XML (XHTML doctype + namespace)
- OCR annotations are converted from relative bottom-left coordinates to absolute top-left pixel coordinates
- PDFs are rasterized to page images (300 DPI) and merged back into a multi-page HOCR document
- CI runs on macOS and uses
misetasks for lint/format/typecheck/test - Releases are automated with
python-semantic-release - Commit messages follow Conventional Commits (validated in CI)
- Engine not discovered: confirm you installed in the active environment, then run the discovery snippet above.
livetextfails: verify macOS major version is 14 or newer.- Non-macOS runtime: expected failure; this engine intentionally supports macOS only.
- PDF OCR issues: ensure Poppler is available when your workflow depends on PDF rasterization tooling.
See CONTRIBUTING.md for contribution workflow and commit message guidance.