🔤 TextScan

TextScan is a modular OpenFilter-based filter for extracting text from video frames using EasyOCR or Tesseract.

It supports frame-by-frame OCR, optional skipping via metadata, and flexible deployment as part of OpenFilter pipelines.

✨ Features

• 🧾 Extracts text using EasyOCR or Tesseract from frames
• 🔍 Supports per-frame metadata control (e.g. skip OCR)
• ⚙️ Configurable via CLI args, code, or environment variables
• 🧩 Plug-and-play compatibility with OpenFilter
• 📤 Outputs recognized text, ocr confidence score and bounding boxes as metadata
• 🔄 Multi-topic processing - processes multiple video regions simultaneously
• 🔀 Data forwarding - forwards non-image frames when enabled
• 📊 Main-first ordering - ensures consistent output structure

📦 Installation

Install the latest version from PyPI:

pip install filter-optical-character-recognition

Or install from source:

# Clone the repo
git clone https://github.com/PlainsightAI/filter-optical-character-recognition.git
cd filter-optical-character-recognition

# (Optional but recommended) create a virtual environemnt:
python -m venv venv && source venv/bin/activate

# Install the filter
make install

💡 The make install target installs openfilter[all], ensuring dependencies like VideoIn and Webvis work out of the box.

🚀 Quick Start (CLI)

Run the OCR Filter using the OpenFilter CLI:

# Most basic version, no annotion or result logging
openfilter run \
  - VideoIn --sources 'file://video_example.mp4!loop' \
  - filter_optical_character_recognition.filter.FilterOpticalCharacterRecognition \
  - Webvis

# Log results into stdout
openfilter run \
  - VideoIn --sources 'file://video_example.mp4!loop' \
  - filter_optical_character_recognition.filter.FilterOpticalCharacterRecognition \
    --mq_log pretty
  - Webvis

# Multi-topic processing with region-based OCR
openfilter run \
  - VideoIn --sources 'file://video_example.mp4!loop' \
  - filter_optical_character_recognition.filter.FilterOpticalCharacterRecognition \
      --ocr_engine easyocr \
      --forward_ocr_texts true \
      --draw_visualization true \
      --topic_pattern "region_.*" \
      --exclude_topics "main" \
      --forward_upstream_data true \
  - Webvis

Or simply:

make run

Then open http://localhost:8000 to view the output.

📄 See the .env.example file for environment variable options.

🧰 Using from PyPI

After installing with:

pip install filter-optical-character-recognition

you can use the OCR Filter directly in code:

Example usage

from openfilter.filter_runtime.filter import Filter
from openfilter.filter_runtime.filters.video_in import VideoIn
from openfilter.filter_runtime.filters.webvis import Webvis
from filter_optical_character_recognition.filter import FilterOpticalCharacterRecognition

if __name__ == "__main__":
    Filter.run_multi([
      (VideoIn, dict(
          sources='file://video_example.mp4!loop',
          outputs='tcp://*:5550'
      )),
      (FilterOpticalCharacterRecognition, dict(
          sources='tcp://localhost:5550',
          outputs='tcp://*:5552',
          draw_visualization=True,
          visualization_topic="main"
      )),
      (Webvis, dict(
          sources='tcp://localhost:5552'
      )),
    ])

🧪 Testing

Run tests locally:

make test

Or run a specific test file:

pytest -v tests/test_filter_ocr.py

Tests cover:

• OCR accuracy and bounding box parsing
• skip_ocr handling
• Frame metadata propagation
• Integration in multi-filter pipelines
• Multi-topic processing and main-first ordering
• Configuration normalization and validation
• Data forwarding behavior

🔧 Special Features

Metadata-Based Skipping

You can skip OCR on specific frames by setting this field:

"meta": {
  "skip_ocr": true
}

This allows selective processing and performance tuning.

🔩 Requirements

The OCR Filter depends on the following tools:

• easyocr
• pytesseract
• Tesseract OCR binary (AppImage or system install)

Ensure the tesseract binary is available in your environment when running OCR with Tesseract.

🤝 Contributing

We welcome contributions! Please read our CONTRIBUTING.md for instructions.

Highlights:

• Format code with black
• Lint with ruff
• Use type hints on public methods
• Sign commits using DCO (git commit -s)
• Include tests when relevant

📄 License

Licensed under the Apache 2.0 License.

🙏 Acknowledgements

Thanks for using TextScan! For questions or feature requests, open a GitHub issue.