Metadata-Version: 2.4
Name: ocr-magnifier-realtime
Version: 0.1.0
Summary: Real-time screen magnifier with OCR and translation capabilities using PyQt5 and Tesseract.
Author-email: "Teody A. Banagan" <teody882011@gmail.com>
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: PyQt5>=5.15.0
Requires-Dist: pytesseract>=0.3.10
Requires-Dist: Pillow>=9.0.0
Requires-Dist: googletrans==4.0.0-rc1

# Realtime OCR & Multilingual Screen Magnifier (`OCR_Magnifier_Realtime`)

`OCR_Magnifier_Realtime` is a lightweight, asynchronous Python application and middleware designed for real-time desktop screen extraction, optical character recognition (OCR), and multilingual machine translation.

The framework operates in two distinct execution modes:
1. **Interactive Desktop GUI Application (`ocr-desktop`)**: A transparent, resizable floating screen magnifier with real-time text extraction and translation feedback windows.
2. **Headless API Middleware (`ocr-api`)**: A background service featuring zero-UI overhead, flat-file configuration parsing (`Translation_Settings.txt`), and automated log-based data output (`Translation_Log.txt`) for local inter-process communication (IPC) and automation pipelines.

---

## Key Features

- **Asynchronous Execution Architecture**: Non-blocking `QThread` pipeline prevents GUI freezing during screen capture, OCR processing, and API calls.
- **Dynamic Transparent Magnifier Overlay**: Floating frame with customizable dimensions, visual dashed border indicators, and intuitive corner drag handles.
- **Multilingual Support**: Real-time extraction and translation across multiple languages including English, German, French, Spanish, and Chinese Simplified.
- **Decoupled Local Middleware / API**: Headless mode acts as a lightweight local server alternative using simple flat-file serialization for resource-constrained desktop environments.

---

## Prerequisites

### 1. System Dependency: Tesseract OCR
This project requires the **Tesseract OCR Engine** installed on your operating system:
- **Windows**: Download installer from [UB-Mannheim/tesseract](https://github.com/UB-Mannheim/tesseract/wiki) and ensure Tesseract is added to your system `PATH`. Download language packs (`.traineddata` files, e.g., `deu.traineddata`, `fra.traineddata`) into your `tessdata` directory for non-English OCR.
- **Linux (Ubuntu/Debian)**:
  ```bash
  sudo apt-get update
  sudo apt-get install tesseract-ocr tesseract-ocr-deu tesseract-ocr-fra tesseract-ocr-spa tesseract-ocr-chi-sim
  ```
- **macOS**:
  ```bash
  brew install tesseract tesseract-lang
  ```

---

## Installation

Install the package via `pip`:

```bash
pip install ocr-magnifier-realtime
```

Or install from source in editable mode:

```bash
git clone https://github.com/teody882011/OCR_Magnifier_Realtime.git
cd OCR_Magnifier_Realtime
pip install -e .
```

---

## Usage Guide

### 1. Interactive Desktop GUI Application
Run the interactive desktop tool directly from your CLI:

```bash
ocr-desktop
```

* **Controls**: Position the transparent frame over any text on your screen. Adjust the width and height inputs or drag using the red corner dots. Select target languages dynamically using the dropdown menu.

---

### 2. Headless API Middleware
Run the headless API background service from your CLI:

```bash
ocr-api
```

#### Configuration (`Translation_Settings.txt`)
The headless middleware automatically reads configuration properties from `Translation_Settings.txt` located in your current execution directory:

```ini
Source_Image=English;
Image_To_Text_OCR=German;
Translation=English;
Magnifier_Frame_Size=(700, 450);
Magnifier_Frame_TopPosition=(100, 100);
```

#### Data Output Log / Local API (`Translation_Log.txt`)
Every execution loop (default: 1.5s), the headless service updates and overwrites `Translation_Log.txt` with the latest extracted payload data:

```text
Timestamp: 2026-10-19 00:30:12
OCR_Language: German
Translation_Language: English
----------------------------------------
[Original_Text]
Maschinelles Lernen ermöglicht Systemen, aus Daten zu lernen.

[Translated_Text]
Machine learning allows systems to learn from data.
```

External consumer applications or scripts can read `Translation_Log.txt` in real time to consume extracted and translated text streams.

---

## Project Structure

```text
OCR_Magnifier_Realtime/
├── pyproject.toml
├── README.md
├── LICENSE
├── src/
│   └── ocr_magnifier_realtime/
│       ├── __init__.py
│       ├── api_app.py
│       ├── desktop_app.py
│       └── worker.py
└── tests/
    └── __init__.py
```

---

## License

Distributed under the MIT License. See `LICENSE` for details.

## ⚖️ Legal Manifest & Copyright Notice

* **Copyright Notice:** `Copyright (c) 2026 Teody Arboneda Banagan. All rights reserved.`
* **Open Source License:** Distributed globally under the highly permissive **MIT License**.

---

## 🔬 About the Author & Project Maintainer

**Teody Arboneda Banagan, PhD (Candidate)**
*Solution Architect, AI Engineer and Researcher*
* **Email:** teody882011@gmail.com

### Professional Stature & Domain Expertise
The structural maintenance, systems design, and algorithmic orchestration of this framework are driven by 20 years of progressive IT experience and top-tier credentials spanning international enterprise teams:
* **Doctor of Philosophy (PhD) in IT Candidate** — University of San Carlos, specializing in Advanced IT Frameworks, Robotics Process Automation, Computer Vision, and Enterprise AI Architectures.
* **Master in Information Technology (MIT)** — Cebu Institute of Technology - University.
* **Peer-Reviewed Reviewer & Author** — Invited Peer Reviewer for Scopus-indexed and Web of Science international journals.
