textsnap

CPU-based OCR tool – images, screenshots, URLs to text. No GPU, no cloud, one command.

textsnap converts images, screenshots, image URLs, or webpages into text using PaddleOCR-VL-1.5 (0.9B parameters) running locally on CPU via ONNX Runtime.

Features

• 📷 Local images – PNG, JPG, WebP, BMP, GIF, TIFF, and more
• 🔗 Image URLs – Download and OCR directly from URLs
• 🌐 Webpages – Extracts the main article image and OCRs it
• 📋 Clipboard – textsnap (no arguments) reads image from clipboard, writes text back
• 📝 Markdown output – Preserves headers, bold, tables from OCR
• 📄 Plaintext mode – --plaintext strips markdown formatting
• 🔒 SHA-256 verification – All model files verified on download
• 📦 Portable mode – Drop onnx/ folder next to binary, no download needed

Quick Start

# Install (system-specific)
cargo install textsnap

# OCR from clipboard
textsnap

# OCR from file
textsnap screenshot.png

# OCR from image URL
textsnap https://example.com/document.jpg

# OCR from webpage (extracts main article image)
textsnap https://en.wikipedia.org/wiki/Optical_character_recognition

# Plaintext output
textsnap --plaintext screenshot.png

# Custom output path
textsnap -o result.txt document.png

Installation

From Source

git clone https://github.com/TH07008/textsnap.git
cd textsnap

# Install ONNX Runtime (system dependency)
# Ubuntu/Debian:
sudo apt install libonnxruntime-dev
# macOS:
brew install onnxruntime

# Build
cargo build --release

# The binary is at target/release/textsnap

Model Files

On first run, textsnap automatically downloads the PaddleOCR-VL-1.5 model (~890 MB) from HuggingFace to ~/.cache/textsnap/.

For portable/offline use, download the model files manually and place them next to the binary:

textsnap --model-dir ./onnx  # use models from specific directory
# OR place the onnx/ folder next to the binary (portable mode)

Verify Models

textsnap --generate-checksums  # print SHA-256 of local models
textsnap --no-verify           # skip checksum verification

CLI Reference

Flag	Description
textsnap [INPUT]	Input: file path, URL, or empty for clipboard
-o, --output <PATH>	Custom output file path (default: textsnaps/{stem}_ocr.txt)
--plaintext	Strip markdown formatting from output
--max-tokens <N>	Maximum tokens to generate (default: 2048)
--max-pixels <N>	Maximum image pixels for preprocessing
--model-dir <PATH>	Custom model directory
--no-verify	Skip SHA-256 model verification
-v, --verbose	Show diagnostic output on stderr
-q, --quiet	Suppress non-error output
--generate-checksums	Print SHA-256 of model files and exit

Environment Variables

Variable	Description
TEXTSNAP_DECODE_THREADS	Max threads for decoder (default: 4)

Architecture

textsnap
├── cli.rs              # Argument parsing (clap)
├── constants.rs        # PaddleOCR-VL constants, token IDs, file paths
├── input.rs            # Input detection: clipboard, file, image URL, webpage
├── model/mod.rs        # Model download, cache, SHA-256 verification
├── preprocess.rs       # smart_resize, patchify, tensor formatting
├── decoder.rs          # ONNX sessions, KV-cache, autoregressive decoding
├── output.rs           # File output, plaintext conversion, clipboard
└── main.rs             # Pipeline orchestration

Pipeline

1. Input Detection → Clipboard, local file, image URL, or webpage URL
2. Model Loading → Download from HuggingFace (cached) or use portable onnx/ folder
3. Preprocessing → smart_resize (fit to pixel budget, align to 28px grid) → patchify (split into 14×14 patches)
4. Vision Encoding → ONNX q4-quantized vision encoder → image embeddings
5. Autoregressive Decoding → Greedy decoding with KV-cache + N-gram repetition blocking
6. Output → Write text file, copy to clipboard (clipboard input), print path to stdout

Tech Stack

Component	Crate
CLI	clap
Image processing	image
Tensor operations	ndarray
Tokenizer	tokenizers (Hugging Face)
HTTP client	reqwest
Clipboard	arboard
Web scraping	scraper + url
SHA-256	sha2
Progress bars	indicatif
Error handling	anyhow + thiserror

Roadmap

• ONNX Runtime integration (link ort crate for actual OCR inference)
• PDF support (extract pages as images)
• Batch processing (multiple images in one run)
• Streaming output (show tokens as they're generated)
• Configuration file (~/.config/textsnap/config.toml)
• Automatic model updates (--update-model)
• GPU acceleration via CUDA ONNX Runtime

License

MIT