Auto Image Occlusion - Anki Addon

Automatically detect text regions in images and create Image Occlusion shapes with one click. Works with Anki's native Image Occlusion editor (25.09+).

Inspired by logseq-anki-sync

Features

• One-click text detection via magic wand button in the IO toolbar
• Changeable Merge Factor input right next to the magic wand (scroll wheel or type to adjust line-grouping tolerance on the fly)
• Keyboard shortcut: Ctrl+Shift+X
• Skips existing occlusions (collision detection)
• Merges multi-line labels (configurable & dynamically adjustable)
• Works with 100+ Tesseract languages
• Zero Python dependencies (no Pillow, no pytesseract, no pip downloads)

Installation

Prerequisites: Tesseract OCR

Linux:

sudo apt-get install tesseract-ocr

macOS:

brew install tesseract

Windows: Download from GitHub releases, add C:\Program Files\Tesseract-OCR to PATH.

Additional languages: Install via package manager (e.g. sudo apt-get install tesseract-ocr-spa) or download .traineddata files from tessdata into Tesseract's tessdata directory.

Install Addon

AnkiWeb: Tools > Add-ons > Get Add-ons > code 1414192727

Manual: Copy this folder to your Anki addons directory:

• Windows: %APPDATA%\Anki2\addons21\
• macOS: ~/Library/Application Support/Anki2/addons21/
• Linux: ~/.local/share/Anki2/addons21/

Restart Anki. The addon is ready to use immediately with zero setup.

Usage

1. Open Add cards, select Image Occlusion note type
2. Load your image
3. Click the magic wand button or press Ctrl+Shift+X
4. Wait 2-10 seconds for OCR processing
5. Adjust the generated occlusion boxes as needed
6. Click Add to create your cards

Configuration

Tools > Add-ons > Auto Image Occlusion > Config

{
    "tesseract_lang": "eng",
    "min_confidence": 48,
    "min_width": 4,
    "min_height": 4,
    "min_area_percent": 0.0001,
    "vertical_merge_factor": 0.8,
    "box_padding": 4,
    "button_shortcut": "Ctrl+Shift+X"
}

See config.md for detailed examples.

How It Works

1. User clicks button, JS captures the image as base64
2. Image sent to Python via pycmd()
3. Tesseract runs PSM 12 (sparse text detection)
4. Words are grouped by line, filtered by confidence/size/text-length
5. Vertically close lines are merged (e.g. multi-line labels)
6. Collision check against existing canvas shapes
7. Results sent back to JS, which creates Rectangle shapes on the canvas

Troubleshooting

"TesseractNotFoundError": Tesseract isn't installed or not on PATH. Run tesseract --version to verify. On macOS with Homebrew, set tesseract_cmd in config (e.g. "/opt/homebrew/bin/tesseract").

"No text detected": Lower min_confidence (try 35) and min_area_percent (try 0.00005). Ensure image has clear, readable text.

"OCR timeout": Image too large. Reduce to ~1920px width.

Poor accuracy: Adjust min_confidence up (fewer false positives) or down (catch more text).

Architecture

__init__.py             # Addon entry point
addon.py                # Hook registration
editor_integration.py   # JS injection via editor_mask_editor_did_load_image hook
js_builder.py           # Generates injected JavaScript (button, OCR flow, canvas interaction)
message_handler.py      # pycmd() message routing (JS <-> Python)
ocr_engine.py           # Native Tesseract runner (PSM 12, line grouping, merging)

Credits

• logseq-anki-sync - Original auto-detection concept
• Tesseract OCR - Text detection engine
• Magic wand icon: Material Design Icons (mdiAutoFix)

License

GNU AGPL v3+ (same as Anki)