Metadata-Version: 2.4
Name: parkocr
Version: 0.1.1
Summary: Automatic license plate recognition using YOLOv8 and EasyOCR, with ROI filtering, FIFO output, and screenshot support.
Author-email: João Luiz Thomazetti <joaoluizthomazetti@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/JoaoLuizThomazetti/parkocr
Project-URL: Repository, https://github.com/JoaoLuizThomazetti/parkocr
Project-URL: Issues, https://github.com/JoaoLuizThomazetti/parkocr/issues
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: opencv-python
Requires-Dist: numpy
Requires-Dist: easyocr
Requires-Dist: ultralytics
Dynamic: license-file

# ParkOCR

ParkOCR is a Python library for automatic license plate recognition using **YOLOv8** for detection and **EasyOCR** for text recognition.  
It is designed to work with RTSP streams (e.g., IP cameras), webcams, or video files.

## ✨ Features

- YOLOv8 for plate localization (supports `n`, `s`, `m`, `l`, `x` models).
- EasyOCR for text extraction.
- ROI filtering: only detect plates inside a defined region.
- Headless mode (no window display).
- Prevents freezing on the same consecutive plate.
- Optional FIFO output for inter-process communication.
- Screenshot saving:
  - `screenshot=None`: disabled
  - `screenshot="full"`: saves full frame
  - `screenshot="roi"`: saves only the region of interest

## 📦 Installation

```bash
pip install parkocr
```

## 🚀 Usage

### Basic example

```python
from parkocr.detector import Detector

detector = Detector(
    rtsp_url="rtsp://user:password@192.168.0.100:554/onvif1",
    model_size=0,  # 0=nano, 1=small, 2=medium, 3=large, 4=xlarge
    headless=True,
    screenshot="roi",  # options: None, "full", "roi"
)

detector.run()
```

### With FIFO output

```python
detector = Detector(
    rtsp_url="rtsp://user:password@192.168.0.100:554/onvif1",
    fifo_output="/tmp/plates_fifo",
    headless=True
)
detector.run()
```

Now another process can read detected plates from `/tmp/plates_fifo`.

### With callback

```python
def on_plate(plate):
    print("Detected plate:", plate)

detector = Detector(
    rtsp_url="rtsp://user:password@192.168.0.100:554/onvif1",
    on_detect=on_plate,
    headless=True
)
detector.run()
```

## ⚙️ Parameters

- **rtsp_url (str)**: RTSP stream, file path, or webcam index.
- **model_size (int)**: 0=`n`, 1=`s`, 2=`m`, 3=`l`, 4=`x`. Larger = more accurate, slower.
- **conf_thresh (float)**: YOLO detection confidence threshold.
- **roi (tuple[int, int, int, int] | None)**: Region of interest (x1, y1, x2, y2). Defaults to central ROI.
- **headless (bool)**: Disable display windows and overlays.
- **window_size (tuple[int, int])**: Window size for display.
- **process_interval_s (float)**: Seconds between detection cycles.
- **freeze_seconds (float)**: How long to freeze the display after detection.
- **ocr_langs (list[str])**: OCR languages for EasyOCR.
- **on_detect (callable)**: Callback called with detected plate text.
- **min_ocr_conf (float)**: Minimum OCR confidence.
- **fifo_output (str | None)**: Path to FIFO file to send plates.
- **screenshot (str | None)**: `None`, `"full"`, or `"roi"`.

## 📂 Project structure

```
parkocr/
├── detector.py
├── __init__.py
README.md
pyproject.toml
```

## 📝 License

MIT © 2025 João Luiz Thomazetti
