Metadata-Version: 2.4
Name: ocr-advance-magnifier-realtime
Version: 0.1.1
Summary: A real-time screen magnifier with advanced VLM OCR (Qwen2.5-VL via LM Studio) capabilities.
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
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: PyQt5>=5.15.0
Requires-Dist: Pillow>=9.0.0
Requires-Dist: openai>=1.0.0

# OCR Advance Magnifier Realtime

A real-time screen magnifier and advanced Vision-Language Model (VLM) Optical Character Recognition (OCR) desktop application powered by **Qwen2.5-VL** via **LM Studio**. 

This tool allows you to place a movable, transparent magnifier frame anywhere on your screen to instantly capture, process, and extract complex text types—including handwritten notes, vehicle license plates, receipts, and product labels.

---

## Features

* **Interactive Magnifier Overlay**: Features a dashed blue frame with 4 clickable red corner drag handles so you can position it precisely over any UI element, document, or video stream.
* **Advanced VLM OCR Modes**: Powered by Qwen2.5-VL (via LM Studio local API) with specialized modes:
  * *General Text*
  * *Handwritten*
  * *Vehicle Plate*
  * *Receipt*
  * *Product Labels*
* **Dual Operation Modes**:
  * **Desktop App (`ocr-magnifier-desktop`)**: Full GUI control panel with adjustable frame sizes, live mode switching, and real-time text output views.
  * **API / Headless App (`ocr-magnifier-api`)**: Background monitoring service that logs structured OCR output automatically to `Translation_Log.txt`.
* **PyPI Ready**: Clean packaging structure built with modern Python standards (`pyproject.toml`).

---

## Prerequisites

1. **LM Studio**: Download and run [LM Studio](https://lmstudio.ai/).
2. **Model**: Load the **Qwen2.5-VL-3B-Instruct** model in LM Studio.
3. **Local Server**: Start the **Local Server** inside LM Studio (running at `http://127.0.0.1:1234`).

---

## Installation

You can install the package directly from PyPI (once published):

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

Or for local development installation (editable mode):
```bash
git clone https://github.com/teody882011/OCR_Advance_Magnifier_Realtime.git
cd OCR_Advance_Magnifier_Realtime
pip install -e .
```

---

## Usage

### 1. Run the Interactive Desktop Application
Launch the graphical control panel and movable screen frame:
```bash
ocr-magnifier-desktop
```

### 2. Run the Headless Background Service
Launch the background logging application (writes results continuously to `Translation_Log.txt`):
```bash
ocr-magnifier-api
```

---

## Configuration

The application reads and writes settings dynamically via `Translation_Settings.txt`:

```text
OCR_Mode=General Text;
Magnifier_Frame_Size=(700, 450);
Magnifier_Frame_TopPosition=(100, 100);
```

Available `OCR_Mode` values:
* `General Text`
* `Handwritten`
* `Vehicle Plate`
* `Receipt`
* `Product Labels`

---

## Project Structure

```text
OCR_Advance_Magnifier_Realtime/
│
├── pyproject.toml         # Build system and dependency metadata
├── README.md              # Documentation
└── src/
    └── ocr_advance_magnifier_realtime/
        ├── __init__.py    # Package version and initialization
        ├── api_app.py     # Headless background processing script
        ├── desktop_app.py # Interactive PyQt5 desktop GUI & overlay
        └── worker.py      # Qwen2.5-VL multimodal client (LM Studio)
```

---

## Building and Publishing to PyPI

If you want to compile and publish updates to PyPI:

1. **Install build requirements:**
   ```bash
   pip install --upgrade build twine setuptools wheel
   ```

2. **Clean existing build artifacts (if any):**
   ```bash
   rm -rf build/ dist/ src/*.egg-info
   ```

3. **Build the package distribution:**
   ```bash
   python -m build
   ```

4. **Check distribution files:**
   ```bash
   twine check dist/*
   ```

5. **Upload to PyPI:**
   ```bash
   python -m twine upload dist/*
   ```

---

## License

Distributed under the **MIT License**.


## ⚖️ 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
Built on 20 years of progressive IT experience spanning international enterprise environments, this framework leverages deep practical expertise in Advanced IT Architecture, Robotic Process Automation, Computer Vision, IoT, Drone/UAV Programming, and Generative/Agentic AI:
* **Doctor of Philosophy (PhD) in IT Candidate — University of San Carlos.
* **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.
