{"id":9149,"library":"ocrmac","title":"ocrmac","description":"ocrmac is a Python wrapper designed to extract text from images specifically on macOS systems. It leverages Apple's Vision framework to provide fast and accurate Optical Character Recognition (OCR) capabilities. The library is currently at version 1.0.1 and maintains an active development and release cadence, with updates addressing features and bug fixes. It requires macOS 10.15 (Catalina) or newer.","status":"active","version":"1.0.1","language":"en","source_language":"en","source_url":"https://github.com/straussmaximilian/ocrmac","tags":["OCR","macOS","Apple Vision Framework","image processing"],"install":[{"cmd":"pip install ocrmac","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"CLI utilities","package":"click","optional":false},{"reason":"Image processing (PIL images)","package":"pillow","optional":false},{"reason":"Core dependency for macOS Vision framework integration","package":"pyobjc-framework-vision","optional":false}],"imports":[{"note":"Imports the main module, which contains the OCR class and helper functions.","symbol":"ocrmac","correct":"from ocrmac import ocrmac"},{"note":"Directly imports the OCR class for object-oriented usage.","symbol":"OCR","correct":"from ocrmac.ocrmac import OCR"}],"quickstart":{"code":"from ocrmac import ocrmac\nfrom PIL import Image\nimport os\n\n# Create a dummy image for demonstration purposes\ndummy_image_path = 'test_image.png'\nimg = Image.new('RGB', (60, 30), color = 'red')\nfrom PIL import ImageDraw, ImageFont\nd = ImageDraw.Draw(img)\ntry:\n    # Use a system font path for broader compatibility\n    font = ImageFont.truetype(\"/System/Library/Fonts/Supplemental/Arial.ttf\", 12)\nexcept IOError:\n    font = ImageFont.load_default() # Fallback\nd.text((10,10), \"Hello OCR!\", fill=(0,0,0), font=font)\nimg.save(dummy_image_path)\n\n# Perform OCR using the OCR class\ntry:\n    annotations = ocrmac.OCR(dummy_image_path, language_preference=['en-US']).recognize()\n    print(\"Detected annotations:\")\n    for text, confidence, bounding_box in annotations:\n        print(f\"  Text: '{text}', Confidence: {confidence:.2f}, Bounding Box: {bounding_box}\")\n\n    # Alternatively, use the functional interface\n    text_output = ocrmac.text_from_image(dummy_image_path, language_preference=['en-US'])\n    print(\"\\nDetected text (functional interface):\")\n    print(text_output)\n\nfinally:\n    # Clean up the dummy image\n    if os.path.exists(dummy_image_path):\n        os.remove(dummy_image_path)","lang":"python","description":"This quickstart demonstrates how to use `ocrmac` to extract text from an image. It covers both the class-based `ocrmac.OCR` approach and the functional `ocrmac.text_from_image` method, including setting language preferences. A dummy image is created for a runnable example."},"warnings":[{"fix":"Ensure deployment on a compatible macOS system (10.15 or newer).","message":"ocrmac is a macOS-exclusive library, relying on Apple's Vision framework. It will not function on Windows, Linux, or older macOS versions (requires macOS 10.15+).","severity":"breaking","affected_versions":"All versions"},{"fix":"Consult the `ocrmac` documentation or source code for a list of supported language codes (e.g., 'en-US', 'zh-Hans', 'de-DE').","message":"Using an unsupported or misspelled language code in `language_preference` will result in an error, often indicating available languages.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Choose the `recognition_level` ('fast' or 'accurate') that best suits your application's requirements for speed versus accuracy. Default is 'accurate'.","message":"The `recognition_level` parameter for OCR can be set to 'fast' or 'accurate'. 'Fast' provides quicker results but may sacrifice precision, while 'accurate' offers higher precision at a slower speed.","severity":"gotcha","affected_versions":"All versions"},{"fix":"When utilizing specific features or performance characteristics, ensure you explicitly set the `framework` parameter (e.g., `framework='livetext'`) in the `OCR` constructor or `text_from_image` function.","message":"ocrmac version 1.0.0 introduced support for using either the 'vision' or 'livetext' framework as the backend. Not specifying or incorrectly specifying the 'framework' parameter might lead to unexpected behavior or errors if you intend to use the newer LiveText features.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure your image input is either a string representing the file path or a valid Pillow (PIL) Image object.","cause":"Attempting to pass an image object that is neither a string path nor a `PIL.Image.Image` object to the OCR functions.","error":"ValueError: Invalid image format. Image must be a path or a PIL image."},{"fix":"Set `recognition_level` to either `'accurate'` or `'fast'`.","cause":"An unrecognized string was passed to the `recognition_level` parameter.","error":"ValueError: Invalid recognition level. Recognition level must be 'accurate' or 'fast'."},{"fix":"Provide a list of valid BCP-47 language identifiers (e.g., `['en-US']`, `['zh-Hans', 'de-DE']`). The error message itself might guide you to the available options.","cause":"The `language_preference` list contains an unsupported or incorrectly formatted language code.","error":"If you set a wrong language you will see an error message showing the languages available."}]}