When to use

• •Convert textbook/lecture images to markdown notes
• •Batch OCR processing of scanned documents
• •Extract text from image sequences (iPhone photos, screenshots)
• •Create searchable markdown from visual content
• •Process documents privately without cloud services

ollama-deepseek-ocr-tool Skill

Purpose

This skill provides access to ollama-deepseek-ocr-tool, a CLI tool for fast, private batch OCR processing using DeepSeek-OCR via Ollama. Converts sequences of images (textbook pages, slides, scans) into a single coherent markdown document.

Key capabilities:

• •⚡ Fast processing (~3s per image on M4)
• •🔒 Private - runs entirely locally
• •📝 Clean markdown output (tables, headings, lists)
• •🔄 Natural sorting (IMG_1 < IMG_2 < IMG_10)
• •💰 Free - no API costs or rate limits

When to Use This Skill

Use this skill when:

• •Converting textbook chapters to Obsidian notes
• •Processing lecture slides or handouts to markdown
• •Extracting text from scanned documents
• •Creating searchable study materials from images
• •Need comprehensive examples and troubleshooting

Do NOT use this skill for:

• •Cloud-based OCR (this is local-only)
• •Describing image content (extracts text only)
• •Handwritten text recognition (printed text only)
• •Real-time streaming OCR (batch processing only)

CLI Tool: ollama-deepseek-ocr-tool

The ollama-deepseek-ocr-tool processes multiple images in sequence and creates a single markdown document with extracted text. Images are sorted naturally and text is appended sequentially for coherent reading.

Installation

# Clone and install
git clone https://github.com/dnvriend/ollama-deepseek-ocr-tool.git
cd ollama-deepseek-ocr-tool
uv tool install .

Prerequisites

1. •

   Ollama - Local LLM runtime

   bash

   brew install ollama
   ollama serve
   

2. •

   DeepSeek-OCR model (~6GB download)

   bash

   ollama pull deepseek-ocr
   

3. •

   Python 3.14+ and uv package manager

Quick Start

# Example 1: Process textbook chapter from iPhone photos
ollama-deepseek-ocr-tool "IMG_*.png" chapter-3-notes.md

# Example 2: Convert lecture slides to markdown
ollama-deepseek-ocr-tool "lecture-week5/*.jpg" week5-summary.md

# Example 3: With verbose logging to debug issues
ollama-deepseek-ocr-tool "*.png" output.md -vv

Main Command - Batch OCR Processing

Process images matching a glob pattern and create a markdown document.

Usage:

ollama-deepseek-ocr-tool GLOB_PATTERN OUTPUT_FILE [OPTIONS]

Arguments:

• •GLOB_PATTERN: Pattern to match images (e.g., ".png", "dir/.jpg")
• •OUTPUT_FILE: Path to output markdown file (will be overwritten)
• •-v/-vv/-vvv: Verbosity (INFO/DEBUG/TRACE)
• •--help: Show comprehensive help with examples
• •--version: Show version

Examples:

# Basic: Process all PNGs in current directory
ollama-deepseek-ocr-tool "*.png" output.md

# Process specific directory
ollama-deepseek-ocr-tool "textbook-ch3/*.jpg" chapter-3.md

# With verbose logging
ollama-deepseek-ocr-tool "*.png" output.md -vv

# Preview help (shows all examples)
ollama-deepseek-ocr-tool --help

Output Format:

<!-- Source: IMG_4170.png -->

[extracted text from image 1]

---

<!-- Source: IMG_4171.png -->

[extracted text from image 2]

Multi-Level Verbosity Logging

Control logging detail with progressive verbosity levels. All logs output to stderr.

Logging Levels:

Examples:

# INFO level - see operations
ollama-deepseek-ocr-tool command -v

# DEBUG level - see detailed info
ollama-deepseek-ocr-tool command -vv

# TRACE level - see all internals
ollama-deepseek-ocr-tool command -vvv

What Can Be Extracted

Text & Formatting:

• •✅ Headings (H1, H2, H3)
• •✅ Body text with bold/italic
• •✅ Bulleted and numbered lists
• •✅ Multi-column layouts

Tables:

• •✅ Clean markdown table format
• •✅ Headers and structure preserved
• •✅ Merged cells handled

Diagrams & Figures:

• •✅ Text labels extracted
• •✅ Figure captions captured
• •❌ Visual content not described
• •❌ Flowchart arrows not preserved

Performance Characteristics

• •Speed: ~3 seconds per image (M4 MacBook)
• •Memory: ~6GB (DeepSeek-OCR model)
• •Throughput: ~20 images per minute
• •Scalability: Sequential processing (no parallel batching)

Common Issues

Issue: "No files match pattern"

# Check your glob pattern and current directory
ls *.png  # Verify files exist

# Use absolute or relative paths correctly
ollama-deepseek-ocr-tool "./images/*.png" output.md

Issue: "Connection refused" / "OCR extraction failed"

# Ensure Ollama is running
ollama serve

# Verify model is installed
ollama list | grep deepseek-ocr

# Pull model if missing
ollama pull deepseek-ocr

Issue: Poor quality extraction

• •Use -vv flag to see word counts and verify extraction
• •Check image quality (resolution, clarity)
• •For complex layouts, results may vary
• •Tables and diagrams work best with clear text

Issue: Slow processing

• •Expected: ~3 seconds per image on M4
• •Check if Ollama is using GPU acceleration
• •Sequential processing is by design (6GB model)

Getting Help

# Show comprehensive help with examples
ollama-deepseek-ocr-tool --help

# Use verbose logging to debug
ollama-deepseek-ocr-tool "*.png" output.md -vv

Exit Codes

• •0: Success - all images processed
• •1: Validation error - no files match pattern or invalid arguments
• •2: Runtime error - Ollama connection failed or model not found

Best Practices

1. •Organize images before processing: Name files sequentially (IMG_001, IMG_002) for natural sorting
2. •Use descriptive output names: chapter-3-entrepreneurship.md not output.md
3. •Start with small batches: Test with 2-3 images first to verify quality
4. •Enable verbose logging for debugging: Use -vv to see extraction progress and word counts
5. •Review output after processing: OCR may miss formatting or misread complex layouts
6. •Keep images at good resolution: Higher quality = better extraction
7. •Process similar content together: Keep textbook pages separate from diagrams

Resources

• •GitHub: https://github.com/dnvriend/ollama-deepseek-ocr-tool
• •Python Package Index: https://pypi.org/project/ollama-deepseek-ocr-tool/
• •Documentation: <!-- TODO: Add documentation URL if available -->