Auto Image Occlusion — Automatic Image Occlusion for Anki

Automatically detect text regions in images and create Image Occlusion shapes with a single click. Ideal for diagrams, anatomy labels, flowcharts, and other study materials with scattered or multi-line labels.

Key features

• One-click auto-detection of text regions powered by Tesseract OCR (PSM 12 — sparse text with OSD)
• Live Line Merge Tolerance in the toolbar:
  • Segmented split button right next to the magic wand ([ 🪄 | ↕ 0.80 ▾ ])
  • Floating presets popover (Separate Lines 0.00, Tight Spacing 0.40, Standard 0.80, Wide Spacing 1.20, Aggressive Merge 1.50)
  • Precision slider & numeric input (0.00 to 1.50 with 0.01 fine-tuning)
  • Smooth mouse-wheel scrolling over the button or inputs to adjust tolerance by ±0.01 on the fly (or ±0.05 with Shift)
• Smart Typographic Line Merging: Automatically unifies multi-line terms using universal typographic continuation rules (lowercase continuation, unclosed parentheses, and hyphens) without merging adjacent independent labels
• Leader-line & diagram noise filtering: Cleans leader-line dashes, dots, and stray diagram artifacts to generate tight, precise occlusion boxes
• Symmetric box padding: Built-in padding (box_padding: 4px) around detected text to eliminate glyph clipping
• Collision detection to preserve existing manually placed occlusions
• Customizable keyboard shortcut (default: Ctrl+Shift+X)
• Zero Python dependencies: No Pillow, no pytesseract, and no dynamic wheel downloads — instant 0ms startup
• Works seamlessly with Anki's native Image Occlusion editor (both Dark and Light modes)

Quick highlights

• Instant & Lightweight: Zero external Python packages to install or compile. Uses Anki's bundled Qt and standard library.
• Fast & Reliable: Tuned specifically for sparse labels, high-density diagrams, and noisy medical/scientific illustrations.
• Intelligent Line Merging: Groups multi-line labels into a single cohesive occlusion card without merging unrelated labels.

Requirements

• Anki 25.09+ (or any Anki version with native Image Occlusion support)
• Tesseract OCR installed on your system

Quick install

1. Install Tesseract on your operating system:

   • Debian / Ubuntu / Mint:

     sudo apt-get install tesseract-ocr
     

   • macOS (Homebrew):

     brew install tesseract
     

   • Windows: Download and run the installer from UB-Mannheim releases.

2. Install this addon in Anki:

   • Via AnkiWeb code: 1414192727 (Tools > Add-ons > Get Add-ons...)
   • Or unpack the .ankiaddon file directly into your Anki addons21 folder.
   • Restart Anki — it is ready to use immediately with zero additional setup!

Configuration (examples)

Default configuration (Tools > Add-ons > Auto Image Occlusion > Config):

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

More detections (blurry or low-contrast images):

{
  "min_confidence": 35,
  "min_area_percent": 0.00005
}

Fewer false positives (crisp, high-contrast diagrams):

{
  "min_confidence": 60,
  "min_area_percent": 0.001
}

Loose line spacing (diagrams with wider line gaps):

{
  "vertical_merge_factor": 1.2
}

No merging (each line separate):

{
  "vertical_merge_factor": 0
}

Custom shortcut (macOS):

{
  "button_shortcut": "Cmd+Alt+D"
}

Manual Tesseract executable path (if installed in a non-standard location):

{
  "tesseract_cmd": "/opt/homebrew/bin/tesseract"
}

How it works

1. Captures the image directly from Anki's Image Occlusion editor.
2. Direct subprocess invocation of your system's Tesseract binary with TSV structured output.
3. Cleans leader-line artifacts, groups words into lines with confidence anchoring, and unifies multi-line labels using universal typographic continuation rules.
4. Injects native occlusion rectangles with symmetric padding directly onto Anki's Fabric canvas for instant review and fine-tuning.

Troubleshooting tips

• Nothing detected? Verify that Tesseract is installed on your system. Try lowering min_confidence (e.g. 35) or min_area_percent.
• Tesseract not found? Standard paths on Windows, macOS (Homebrew/MacPorts), and Linux are auto-detected. If using a custom installation path, set "tesseract_cmd" in the addon configuration to the absolute path of the binary.
• Labels merged too aggressively or kept separate? Adjust the merge factor directly from the toolbar split button (0.00 keeps every line separate; 0.80 is standard; 1.50 merges wider blocks).
• Timeouts on giant images? Downscale images exceeding ~3000px before occluding for optimal OCR speed.

For full documentation, updates, and issue reports — visit the project on GitHub: https://github.com/BEST8OY/Auto-Image-Occlusion-Anki-Addon