docreader-ocr 0.1.2__py3-none-any.whl

docreader/__init__.py

@@ -0,0 +1,17 @@
+"""
+DocReader - библиотека для распознавания текста с документов
+
+Использование:
+    from docreader import DocReader
+
+    reader = DocReader(models_dir="./models")
+    result = reader.process("passport.jpg")
+    print(result.doc_type)
+    print(result.fields)
+"""
+
+from docreader.pipeline import DocReader
+from docreader.schemas import DocumentResult, ZoneResult
+
+__all__ = ["DocReader", "DocumentResult", "ZoneResult"]
+__version__ = "0.1.0"

docreader/classifier/__init__.py

@@ -0,0 +1,4 @@
+from docreader.classifier.base import BaseClassifier
+from docreader.classifier.mobilenet import MobileNetClassifier
+
+__all__ = ["BaseClassifier", "MobileNetClassifier"]

docreader/classifier/base.py

@@ -0,0 +1,26 @@
+"""Абстрактный интерфейс классификатора документов."""
+
+from abc import ABC, abstractmethod
+import numpy as np
+
+
+class BaseClassifier(ABC):
+    """
+    Интерфейс для классификатора типа документа.
+
+    Чтобы подключить свой классификатор, наследуйтесь от этого класса
+    и реализуйте метод 'predict'.
+    """
+
+    @abstractmethod
+    def predict(self, image: np.ndarray) -> tuple[str, float]:
+        """
+        Классифицирует изображение документа.
+
+        Args:
+            image: BGR изображение (numpy array).
+
+        Returns:
+            Кортеж (метка_класса, уверенность).
+        """
+        ...

docreader/classifier/mobilenet.py

@@ -0,0 +1,80 @@
+"""Классификатор документов на основе MobileNetV2."""
+
+import numpy as np
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from torchvision import models, transforms
+
+from docreader.classifier.base import BaseClassifier
+
+
+class MobileNetClassifier(BaseClassifier):
+    """
+    Классификатор типа документа на основе MobileNetV2.
+
+    Args:
+        weights_path: путь к файлу весов (.pth).
+        class_labels: список меток классов.
+        device: устройство ("cpu" / "cuda").
+    """
+
+    # Стандартные трансформации ImageNet
+    _transform = transforms.Compose([
+        transforms.ToPILImage(),
+        transforms.Resize((224, 224)),
+        transforms.ToTensor(),
+        transforms.Normalize(
+            mean=[0.485, 0.456, 0.406],
+            std=[0.229, 0.224, 0.225],
+        ),
+    ])
+
+    def __init__(
+        self,
+        weights_path: str,
+        class_labels: list[str],
+        device: str = "cpu",
+    ):
+        self._class_labels = class_labels
+        self._device = device
+
+        num_classes = len(class_labels)
+        self._model = self._build_model(num_classes)
+        self._load_weights(weights_path)
+
+    def _build_model(self, num_classes: int) -> nn.Module:
+        net = models.mobilenet_v2(pretrained=False)
+        net.classifier[1] = nn.Linear(net.last_channel, num_classes)
+        return net
+
+    def _load_weights(self, path: str) -> None:
+        state_dict = torch.load(path, map_location=self._device, weights_only=False)
+        new_state_dict = {}
+        for key, value in state_dict.items():
+            if key.startswith("net."):
+                new_key = key[4:]  # Убираем первые 4 символа "net."
+            else:
+                new_key = key
+            new_state_dict[new_key] = value
+
+        self._model.load_state_dict(new_state_dict)
+        self._model.to(self._device)
+        self._model.eval()
+
+    @torch.no_grad()
+    def predict(self, image: np.ndarray) -> tuple[str, float]:
+        """
+        Args:
+            image: BGR изображение.
+
+        Returns:
+            (метка_класса, уверенность)
+        """
+        tensor = self._transform(image).unsqueeze(0).to(self._device)
+        logits = self._model(tensor)
+        probs = F.softmax(logits, dim=1)
+
+        confidence, idx = probs.max(dim=1)
+        label = self._class_labels[idx.item()]
+        return label, confidence.item()

docreader/config.py

@@ -0,0 +1,46 @@
+"""
+Конфигурация пайплайна
+"""
+
+from dataclasses import dataclass, field
+
+DEFAULT_SKIP_OCR_ZONES = frozenset({"stamp", "gerb"})
+
+
+@dataclass
+class PipelineConfig:
+    """
+    Настройки пайплайна распознавания
+    """
+    device: str = "auto"
+
+    # Типы документов и пути к YOLO-моделям (относительно models_dir)
+    detector_weights: dict[str, str] = field(default_factory=lambda: {
+        "attestat": "attestat.pt",
+        "diplom": "diplom.pt",
+        "passport": "passport.pt",
+        "snils": "snils.pt",
+    })
+
+    # Путь к весам классификатора (относительно models_dir)
+    classification_weights: str = "best_doc_classifier.pth"
+
+    class_labels: list[str] = field(default_factory=lambda: [
+        "attestat", "diplom", "passport", "snils", 'other'
+    ])
+
+    # EasyOCR
+    skip_ocr_zones: frozenset[str] = DEFAULT_SKIP_OCR_ZONES 
+    ocr_lang: list[str] = field(default_factory=lambda: ["ru"])
+    ocr_recog_network: str = "custom_example"
+    ocr_download_enabled: bool = False
+
+    enable_deskew: bool = True  # Выравнивание по линиям Хафа
+
+    return_crops: bool = True  # Сохранять кропы зон в результат
+
+    def resolve_device(self) -> str:
+        if self.device != "auto":
+            return self.device
+        import torch
+        return "cuda" if torch.cuda.is_available() else "cpu"

docreader/detector/__init__.py

@@ -0,0 +1,4 @@
+from docreader.detector.base import BaseDetector, Detection
+from docreader.detector.yolo_obb import YoloObbDetector
+
+__all__ = ["BaseDetector", "Detection", "YoloObbDetector"]

docreader/detector/base.py

@@ -0,0 +1,36 @@
+"""Абстрактный интерфейс детектора зон документа."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+import numpy as np
+
+
+@dataclass
+class Detection:
+    """Одна обнаруженная зона."""
+    zone_name: str
+    obb_points: np.ndarray   # shape (4, 2) или (8,)
+    confidence: float
+
+
+class BaseDetector(ABC):
+    """
+    Интерфейс для детектора полей документа.
+
+    Чтобы подключить свой детектор, наследуйтесь и реализуйте `detect`.
+    """
+
+    @abstractmethod
+    def detect(self, image: np.ndarray, doc_type: str) -> list[Detection]:
+        """
+        Обнаруживает зоны (поля) на изображении документа.
+
+        Args:
+            image: BGR изображение.
+            doc_type: тип документа (для выбора нужной модели).
+
+        Returns:
+            Список обнаруженных зон.
+        """
+        ...

docreader/detector/yolo_obb.py

@@ -0,0 +1,57 @@
+"""Детектор зон документа на основе YOLOv8 OBB."""
+
+import os
+import numpy as np
+from ultralytics import YOLO
+
+from docreader.detector.base import BaseDetector, Detection
+
+
+class YoloObbDetector(BaseDetector):
+    """
+    Детектор полей документа через YOLOv8 с ориентированными боксами.
+
+    Args:
+        models_dir: директория с весами YOLO.
+        weights_map: словарь {тип_документа: имя_файла_весов}.
+    """
+
+    def __init__(self, models_dir: str, weights_map: dict[str, str]):
+        self._models: dict[str, YOLO] = {}
+
+        for doc_type, filename in weights_map.items():
+            path = os.path.join(models_dir, filename)
+            if not os.path.isfile(path):
+                raise FileNotFoundError(
+                    f"YOLO weights not found: {path} (doc_type={doc_type})"
+                )
+            self._models[doc_type] = YOLO(path)
+
+    @property
+    def supported_doc_types(self) -> list[str]:
+        return list(self._models.keys())
+
+    def detect(self, image: np.ndarray, doc_type: str) -> list[Detection]:
+        if doc_type not in self._models:
+            raise ValueError(
+                f"No YOLO model for doc_type='{doc_type}'. "
+                f"Available: {self.supported_doc_types}"
+            )
+
+        model = self._models[doc_type]
+        results = model(image)
+
+        detections = []
+        for det in results[0].obb:
+            zone_id = int(det.cls)
+            zone_name = model.names[zone_id]
+            obb_points = det.xyxyxyxy.cpu().numpy().flatten()
+            confidence = float(det.conf.cpu())
+
+            detections.append(Detection(
+                zone_name=zone_name,
+                obb_points=obb_points,
+                confidence=confidence,
+            ))
+
+        return detections

docreader/hub.py

@@ -0,0 +1,182 @@
+"""
+Автоматическая загрузка и кэширование моделей.
+
+Модели скачиваются при первом вызове и сохраняются в:
+    ~/.cache/docreader/models/
+"""
+
+import os
+import hashlib
+import logging
+import tarfile
+from pathlib import Path
+from typing import Optional
+
+import requests
+from tqdm import tqdm
+
+logger = logging.getLogger(__name__)
+
+_BASE_URL = "https://github.com/mishanyacorleone/docreader/releases/download/v0.1.0"
+
+MODEL_REGISTRY: dict[str, dict] = {
+    "best_doc_classifier.pth": {
+        "url": f"{_BASE_URL}/best_doc_classifier.pth",
+        "sha256": "6d56f45bd33f5296f40bbf32c67a46c01914a3ac7a3dcbbf9aa9a0b8402b59c4",
+        "size_mb": 8.75,
+    },
+    "passport.pt": {
+        "url": f"{_BASE_URL}/passport.pt",
+        "sha256": "bebe46bcd4270442c1e14e9b5a403c9f59212d92ed8181af1326f9f80bc0f0c0",
+        "size_mb": 5.55,
+    },
+    "diplom.pt": {
+        "url": f"{_BASE_URL}/diplom.pt",
+        "sha256": "f1848733eefa4741ead199cf8226e2fc141b08b01d625912d19926bb7ebc6387",
+        "size_mb": 5.71,
+    },
+    "attestat.pt": {
+        "url": f"{_BASE_URL}/attestat.pt",
+        "sha256": "9b6eaa5860b0cb0498995c0ab8015a9b85a9a910b429f2bef509e1202232199d",
+        "size_mb": 5.72,
+    },
+    "snils.pt": {
+        "url": f"{_BASE_URL}/snils.pt",
+        "sha256": "84775a6ff1ababb3f8e31a8aa768717cf9d65d8b84df9c0cd48eb7bdaf680218",
+        "size_mb": 5.82,
+    },
+    "easyocr_custom.tar.gz": {
+        "url": f"{_BASE_URL}/easyocr_custom.tar.gz",
+        "sha256": "832ce5a7f3a1086d81beb1c991347e3f545a425646bc87f3f576ae06fecd2420",
+        "size_mb": 87.1,
+        "extract_to": "easyocr"
+    }
+}
+
+def get_cache_dir() -> Path:
+    """Возвращает директорию кэша моделей."""
+    cache = Path(os.environ.get("DOCREADER_CACHE", "~/.cache/docreader"))
+    cache = cache.expanduser() / "models"
+    cache.mkdir(parents=True, exist_ok=True)
+    return cache
+
+
+
+def _sha256_file(path: Path) -> str:
+    """Считает SHA-256 хэш файла."""
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(8192), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _download_file(url: str, dest: Path, expected_sha256: Optional[str] = None):
+    """Скачивает файл с прогресс-баром и проверкой хэша."""
+    logger.info(f"Downloading {url}")
+
+    response = requests.get(url, stream=True, timeout=30)
+    response.raise_for_status()
+
+    total_size = int(response.headers.get("content-length", 0))
+
+    with open(dest, "wb") as f, tqdm(
+        total=total_size,
+        unit="B",
+        unit_scale=True,
+        desc=dest.name,
+    ) as pbar:
+        for chunk in response.iter_content(chunk_size=8192):
+            f.write(chunk)
+            pbar.update(len(chunk))
+
+    # Проверка целостности
+    if expected_sha256:
+        actual = _sha256_file(dest)
+        if actual != expected_sha256:
+            dest.unlink()
+            raise ValueError(
+                f"Hash mismatch for {dest.name}: "
+                f"expected {expected_sha256[:16]}..., "
+                f"got {actual[:16]}..."
+            )
+
+    logger.info(f"Saved to {dest}")
+
+
+def _extract_archive(archive_path: Path, extract_to: Path):
+    """Распаковывает tar.gz архив."""
+    logger.info(f"Extracting {archive_path.name} → {extract_to}")
+    extract_to.mkdir(parents=True, exist_ok=True)
+
+    with tarfile.open(archive_path, "r:gz") as tar:
+        tar.extractall(path=extract_to)
+
+    archive_path.unlink()
+    logger.info(f"Extracted and cleaned up: {archive_path.name}")
+
+
+def ensure_model(filename: str, cache_dir: Optional[Path] = None) -> Path:
+    """
+    Гарантирует наличие файла модели. Скачивает, если отсутствует.
+
+    Args:
+        filename: имя файла из MODEL_REGISTRY.
+        cache_dir: директория кэша (по умолчанию ~/.cache/docreader/models).
+
+    Returns:
+        Путь к файлу модели.
+
+    Raises:
+        KeyError: если файл не зарегистрирован.
+        ConnectionError: если не удалось скачать.
+    """
+    if filename not in MODEL_REGISTRY:
+        raise KeyError(
+            f"Unknown model '{filename}'. "
+            f"Available: {list(MODEL_REGISTRY.keys())}"
+        )
+
+    cache = cache_dir or get_cache_dir()
+    meta = MODEL_REGISTRY[filename]
+
+    if "extract_to" in meta:
+        extract_dir = cache / meta["extract_to"]
+        if extract_dir.exists() and any(extract_dir.iterdir()):
+            logger.debug(f"Already extracted: {extract_dir}")
+            return extract_dir
+        
+        # Скачиваем и распаковываем
+        archive_path = cache / filename
+        archive_path.parent.mkdir(parents=True, exist_ok=True)
+        _download_file(
+            url=meta["url"],
+            dest=archive_path,
+            expected_sha256=meta.get("sha256")
+        )
+        _extract_archive(archive_path, extract_dir)
+        
+        return extract_dir
+    
+    filepath = cache / filename
+    filepath.parent.mkdir(parents=True, exist_ok=True)
+
+    if filepath.exists():
+        logger.debug(f"Model cached: {filepath}")
+        return filepath
+
+    _download_file(
+        url=meta["url"],
+        dest=filepath,
+        expected_sha256=meta.get("sha256"),
+    )
+
+    return filepath
+
+
+def ensure_all_models(cache_dir: Optional[Path] = None) -> Path:
+    """Скачивает все модели. Возвращает директорию кэша."""
+    cache = cache_dir or get_cache_dir()
+    for filename in MODEL_REGISTRY:
+        ensure_model(filename, cache)
+    return cache

docreader/ocr/__init__.py

@@ -0,0 +1,4 @@
+from docreader.ocr.base import BaseOcrEngine, OcrResult
+from docreader.ocr.easyocr_engine import EasyOcrEngine
+
+__all__ = ["BaseOcrEngine", "OcrResult", "EasyOcrEngine"]

docreader/ocr/base.py

@@ -0,0 +1,35 @@
+"""Абстрактный интерфейс OCR-движка."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+import numpy as np
+
+
+@dataclass
+class OcrResult:
+    """Результат OCR для одного кропа."""
+    text: str
+    confidence: float
+
+
+class BaseOcrEngine(ABC):
+    """
+    Интерфейс OCR-движка.
+
+    Чтобы подключить Tesseract, PaddleOCR или что-то ещё —
+    наследуйтесь и реализуйте `recognize`.
+    """
+
+    @abstractmethod
+    def recognize(self, image: np.ndarray) -> OcrResult:
+        """
+        Распознаёт текст на изображении (кропе зоны).
+
+        Args:
+            image: BGR изображение с текстом.
+
+        Returns:
+            OcrResult с текстом и уверенностью.
+        """
+        ...

docreader/ocr/easyocr_engine.py

@@ -0,0 +1,68 @@
+"""OCR-движок на основе EasyOCR."""
+
+from typing import Optional
+from pathlib import Path
+
+import numpy as np
+import easyocr
+
+from docreader.ocr.base import BaseOcrEngine, OcrResult
+
+
+class EasyOcrEngine(BaseOcrEngine):
+    """
+    OCR через EasyOCR (с поддержкой кастомных моделей).
+
+    Args:
+        lang: список языков, например ["ru"].
+        gpu: использовать GPU.
+        model_storage_directory: путь к директории с моделями.
+        user_network_directory: путь к пользовательским сетям.
+        recog_network: имя сети распознавания.
+    """
+
+    def __init__(
+        self,
+        lang: list[str] | None = None,
+        gpu: bool = True,
+        model_storage_directory: Optional[str] = None,
+        user_network_directory: Optional[str] = None,
+        recog_network: Optional[str] = None,
+        download_enabled: bool = False
+    ):
+        # Путь для хранения моделей по умолчанию
+        if model_storage_directory is None:
+            model_storage_directory = str(Path.home() / ".cache" / "docreader" / "easyocr_models")
+            Path(model_storage_directory).mkdir(parents=True, exist_ok=True)
+
+        kwargs = {
+            "lang_list": lang or ["ru"],
+            "gpu": gpu,
+            "download_enabled": download_enabled,
+            "model_storage_directory": model_storage_directory,
+            "verbose": False,
+        }
+
+        if user_network_directory:
+            kwargs["user_network_directory"] = user_network_directory
+        if recog_network:
+            kwargs["recog_network"] = recog_network
+
+        self._reader = easyocr.Reader(**kwargs)
+
+    def recognize(self, image: np.ndarray) -> OcrResult:
+        results = self._reader.readtext(image)
+
+        if not results:
+            return OcrResult(text="", confidence=0.0)
+
+        texts = []
+        confidences = []
+        for _, text, conf in results:
+            texts.append(text)
+            confidences.append(conf)
+
+        combined_text = " ".join(texts).strip()
+        mean_confidence = sum(confidences) / len(confidences) if confidences else 0.0
+
+        return OcrResult(text=combined_text, confidence=mean_confidence)

docreader/pipeline.py

@@ -0,0 +1,242 @@
+"""
+Главный пайплайн распознавания документов.
+"""
+
+import os
+import logging
+from typing import Optional
+from pathlib import Path
+
+import numpy as np
+
+from docreader.config import PipelineConfig
+from docreader.schemas import DocumentResult, ZoneResult
+from docreader.utils import load_image
+from docreader.hub import ensure_model, get_cache_dir
+from docreader.preprocessing import deskew_image, crop_obb_region
+
+from docreader.classifier.base import BaseClassifier
+from docreader.classifier.mobilenet import MobileNetClassifier
+
+from docreader.detector.base import BaseDetector
+from docreader.detector.yolo_obb import YoloObbDetector
+
+from docreader.ocr.base import BaseOcrEngine
+from docreader.ocr.easyocr_engine import EasyOcrEngine
+
+logger = logging.getLogger(__name__)
+
+class DocReader:
+    """
+    Распознавание текста с документов
+    
+    Пайплайн:
+        1. Классификация типа документа
+        2. Выравнивание (опционально)
+        3. Детекция полей через YOLO OBB
+        4. Кроп каждой зоны
+        5. OCR каждого кропа
+        6. Сборка результата
+
+    Примеры:
+        # Стандартное использование
+        reader = DocReader(models_dir="./models")
+        result = reader.process("passport.jpg")
+        print(result.fields)
+
+        # С кастомным OCR-движком
+        my_ocr = MyTesseractEngine()
+        reader = DocReader(models_dir="./models", ocr_engine=my_ocr)
+
+        # С кастомным классификактором
+        my_cls = MyResNetClassifier(weigths="resnet.pth")
+        reader = DocReader(models_dir="./models", classifier=my_cls)
+    """
+
+    def __init__(
+        self,
+        models_dir: str | None,
+        config: Optional[PipelineConfig] = None,
+        classifier: Optional[BaseClassifier] = None,
+        detector: Optional[BaseDetector] = None,
+        ocr_engine: Optional[BaseOcrEngine] = None
+    ):
+        """
+        Args:
+            models_dir: директория с файлами моделей
+            config: конфигурация пайплайна
+            classifier: кастомный классификатор (если None - MobileNetV2)
+            detector: кастомный детектор (если None - YOLO OBB)
+            ocr_engine: кастомный OCR (если None - EasyOCR)
+        """
+
+        self._config = config or PipelineConfig()
+        self._device = self._config.resolve_device()
+        if models_dir is not None:
+            self._models_dir = Path(models_dir)
+            self._auto_download = False
+        else:
+            self._models_dir = get_cache_dir()
+            self._auto_download = True
+
+        logger.info(f"DocReader init: device={self._device}"
+                    f"models_dir={self._models_dir}"
+                    f"auto_download={self._auto_download}")
+
+        self._classifier = classifier or self._init_classifier()
+        self._detector = detector or self._init_detector()
+        self._ocr = ocr_engine or self._init_ocr()
+
+    def _resolve_weights(self, filename: str) -> str:
+        """
+        Возвращает путь к весам, скачивая при необходимости
+        """
+        if self._auto_download:
+            return str(ensure_model(filename, self._models_dir))
+        path = self._models_dir / filename
+        if not path.exists():
+            raise FileNotFoundError(f"Model not found: {path}")
+        return str(path)
+    
+    def _init_classifier(self) -> BaseClassifier:
+        from docreader.classifier.mobilenet import MobileNetClassifier
+
+        weigths = self._resolve_weights(self._config.classification_weights)
+        return MobileNetClassifier(
+            weights_path=weigths,
+            class_labels=self._config.class_labels,
+            device=self._device
+        )
+    
+    def _init_detector(self) -> BaseDetector:
+        from docreader.detector.yolo_obb import YoloObbDetector
+
+        resolved = {}
+        for doc_type, filename in self._config.detector_weights.items():
+            self._resolve_weights(filename)
+            resolved[doc_type] = filename
+        
+        return YoloObbDetector(
+            models_dir=str(self._models_dir),
+            weights_map=resolved
+        )
+
+    def _init_ocr(self) -> BaseOcrEngine:
+        from docreader.ocr.easyocr_engine import EasyOcrEngine
+
+        easyocr_dir = ensure_model("easyocr_custom.tar.gz", self._models_dir) 
+
+        return EasyOcrEngine(
+            lang=["ru"],
+            gpu=(self._device != "cpu"),
+            model_storage_directory=str(easyocr_dir / "model"),
+            user_network_directory=str(easyocr_dir / "user_network"),
+            recog_network="custom_example",
+            download_enabled=False
+        )
+    
+    # Публичный API
+
+    def process(
+        self,
+        source,
+        return_crops: Optional[bool] = None,
+    ) -> DocumentResult:
+        """
+        Полный пайплайн распознавания документа.
+
+        Args:
+            source: путь к файлу или numpy array (BGR)
+            return_crops: сохранять ли кропы зон в результат
+        
+        Returns:
+            DocumentResult
+        """
+
+        save_crops = (
+            return_crops 
+            if return_crops is not None 
+            else self._config.return_crops
+        )
+        image = load_image(source)
+
+        # 1. Классификация
+        doc_type, doc_conf = self._classifier.predict(image)
+        logger.info(f"Classificated as '{doc_type}' (conf={doc_conf:.3f})")
+        
+        supported = self._config.detector_weights.keys()
+        if doc_type not in supported:
+            logger.warning(
+                f"Unknown doc_type '{doc_type}', "
+                f"supported: {list(supported)}. "
+                f"Returning empty result."
+            )
+            return DocumentResult(
+                doc_type=doc_type,
+                doc_confidence=doc_conf,
+                zones=[]
+            )
+
+        if self._config.enable_deskew:
+            image = deskew_image(image)
+
+        detections = self._detector.detect(image, doc_type)
+        logger.info(f"Detected {len(detections)} zones")
+
+        zones: list[ZoneResult] = []
+        for det in detections:
+            zone = self._process_zone(image, det, save_crops)
+            if zone is not None:
+                zones.append(zone)
+        
+        return DocumentResult(
+            doc_type=doc_type,
+            doc_confidence=doc_conf,
+            zones=zones
+        )
+    
+    def process_batch(
+        self,
+        sources: list,
+        return_crops: Optional[bool] = None 
+    ) -> list[DocumentResult]:
+        """
+        Обработка нескольких документов
+        """
+        return [self.process(src, return_crops) for src in sources]
+    
+    # Внутренняя логика
+    
+    def _process_zone(self, image, detection, save_crops):
+        """
+        Обрабатывает одну зону: кроп -> OCR -> ZoneResult
+        """
+        from docreader.detector.base import Detection
+
+        zone_name = detection.zone_name
+
+        if zone_name in self._config.skip_ocr_zones:
+            return ZoneResult(
+                name=zone_name,
+                text="",
+                confidence=detection.confidence,
+                bbox=detection.obb_points.tolist(),
+                crop_image=None
+            )
+        
+        crop = crop_obb_region(image, detection.obb_points)
+        if crop is None or crop.size == 0:
+            logger.warning(f"Empty crop for zone: '{zone_name}', skipping")
+            return None
+
+        
+        ocr_result = self._ocr.recognize(crop)
+
+        return ZoneResult(
+            name=zone_name,
+            text=ocr_result.text,
+            confidence=ocr_result.confidence,
+            bbox=detection.obb_points.tolist(),
+            crop_image=crop if save_crops else None
+        )
+    

docreader/preprocessing/__init__.py

@@ -0,0 +1,3 @@
+from docreader.preprocessing.geometry import deskew_image, crop_obb_region
+
+__all__ = ["deskew_image", "crop_obb_region"]

docreader/preprocessing/geometry.py

@@ -0,0 +1,101 @@
+"""
+Геометрические преобразования: выравнивание и кроп по OBB.
+"""
+
+import math
+import cv2
+import numpy as np
+
+
+def deskew_image(image: np.ndarray) -> np.ndarray:
+    """
+    Выравнивает документ по горизонтали через преобразование Хафа.
+
+    Args:
+        image: BGR изображение.
+
+    Returns:
+        Повёрнутое изображение.
+
+    Raises:
+        ValueError: если линии не найдены.
+    """
+    gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
+    edges = cv2.Canny(gray, 100, 100, apertureSize=3)
+    lines = cv2.HoughLinesP(
+        edges, 1, math.pi / 180.0, 100, minLineLength=100, maxLineGap=5
+    )
+
+    if lines is None or len(lines) == 0:
+        return image
+
+    angles = [
+        math.degrees(math.atan2(y2 - y1, x2 - x1))
+        for [[x1, y1, x2, y2]] in lines
+    ]
+    median_angle = float(np.median(angles))
+
+    h, w = image.shape[:2]
+    center = (w // 2, h // 2)
+    rotation_matrix = cv2.getRotationMatrix2D(center, median_angle, 1.0)
+    return cv2.warpAffine(image, rotation_matrix, (w, h))
+
+
+def crop_obb_region(image: np.ndarray, obb_points: np.ndarray) -> np.ndarray | None:
+    """
+    Вырезает область по 4 точкам OBB и выпрямляет перспективу.
+
+    Если результат вертикальный (высота > ширина), поворачивает на 90°.
+
+    Args:
+        image: исходное BGR изображение.
+        obb_points: массив из 8 координат [x1,y1,x2,y2,x3,y3,x4,y4]
+                    или shape (4, 2).
+
+    Returns:
+        Выпрямленный кроп или None, если размеры некорректны.
+    """
+    pts = np.array(obb_points, dtype=np.float32).reshape(4, 2)
+
+    # Упорядочиваем: top-left, top-right, bottom-right, bottom-left
+    rect = _order_points(pts)
+    tl, tr, br, bl = rect
+
+    width = max(
+        int(np.linalg.norm(br - bl)),
+        int(np.linalg.norm(tr - tl)),
+    )
+    height = max(
+        int(np.linalg.norm(tr - br)),
+        int(np.linalg.norm(tl - bl)),
+    )
+
+    if width <= 0 or height <= 0:
+        return None
+
+    dst = np.array(
+        [[0, 0], [width - 1, 0], [width - 1, height - 1], [0, height - 1]],
+        dtype=np.float32,
+    )
+
+    matrix = cv2.getPerspectiveTransform(rect, dst)
+    warped = cv2.warpPerspective(image, matrix, (width, height))
+
+    # Поворот вертикальных фрагментов
+    h, w = warped.shape[:2]
+    if h > w:
+        warped = cv2.rotate(warped, cv2.ROTATE_90_COUNTERCLOCKWISE)
+
+    return warped
+
+
+def _order_points(pts: np.ndarray) -> np.ndarray:
+    """Упорядочивает 4 точки: TL, TR, BR, BL."""
+    rect = np.zeros((4, 2), dtype=np.float32)
+    s = pts.sum(axis=1)
+    rect[0] = pts[np.argmin(s)]   # top-left
+    rect[2] = pts[np.argmax(s)]   # bottom-right
+    diff = np.diff(pts, axis=1).flatten()
+    rect[1] = pts[np.argmin(diff)]  # top-right
+    rect[3] = pts[np.argmax(diff)]  # bottom-left
+    return rect

docreader/schemas.py

@@ -0,0 +1,50 @@
+from dataclasses import dataclass, field
+from typing import Optional
+
+import numpy as np
+
+
+@dataclass
+class ZoneResult:
+    """
+    Результат распознавания одного поля документа
+    """
+    name: str
+    text: str
+    confidence: float
+    bbox: list[float] = field(default_factory=list)
+    crop_image: Optional[np.ndarray] = None
+
+    def to_dict(self) -> dict:
+        return {
+            "name": self.name,
+            "text": self.text,
+            "confidence": round(self.confidence, 4)
+        }
+    
+
+@dataclass
+class DocumentResult:
+    """
+    Результат обработки одного документа
+    """
+    doc_type: str
+    doc_confidence: float
+    zones: list[ZoneResult] = field(default_factory=list)
+
+    @property
+    def fields(self) -> dict[str, str]:
+        """
+        Словарь: {имя_зоны: распознанный_текст}
+        """ 
+        return {zone.name: zone.text for zone in self.zones}
+    
+    def to_dict(self) -> dict:
+        return {
+            "document": {
+                "doc_type": self.doc_type,
+                "doc_confidence": round(self.doc_confidence, 4),
+                "zones": [zone.to_dict() for zone in self.zones],
+                "fields": self.fields
+            }
+        }

docreader/utils.py

@@ -0,0 +1,38 @@
+"""
+Утилиты для загрузки и базовой обработки изображений
+"""
+
+import cv2
+import numpy as np
+
+
+def load_image(source) -> np.ndarray:
+    """
+    Загружает изображение из разных источников.
+
+    Args:
+        source: путь к файлу (str), numpy array (BGR или RGB)
+    Returns:
+        Изображение в формате BGR (numpy array)
+    Raises:
+        ValueError: если формат не поддерживается или файл не найден
+    """
+    if isinstance(source, str):
+        image = cv2.imread(source)
+        if image is None:
+            raise ValueError(f"Не удалось загрузить изображение: {source}")
+        return image
+    
+    if isinstance(source, np.ndarray):
+        if source.ndim == 3 and source.shape[2] == 3:
+            return source.copy()
+        raise ValueError(f"Неподдерживаемая форма массива: {source}")
+    raise ValueError(f"Неподдерживаемый тип источника: {type(source)}")
+
+
+def bgr_to_rgb(image: np.ndarray) -> np.ndarray:
+    return cv2.cvtColor(image, cv2.COLOR_BGR2RGB)
+
+
+def rgb_to_bgr(image: np.ndarray) -> np.ndarray:
+    return cv2.cvtColor(image, cv2.COLOR_RGB2BGR)

docreader_ocr-0.1.2.dist-info/METADATA

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: docreader-ocr
+Version: 0.1.2
+Summary: Document OCR pipeline: classify → detect fields → recognize text
+Project-URL: Homepage, https://github.com/mishanyacorleone/docreader
+Project-URL: Repository, https://github.com/mishanyacorleone/docreader
+Project-URL: Issues, https://github.com/mishanyacorleone/docreader/issues
+Author-email: Mikhail Kardash <mishutqac@mail.com>, Ruslan Abzelilov <ruslanr26@mail.ru>, Ekaterina Karmanova <monitor81@mail.ru>
+License: MIT
+License-File: LICENSE
+Keywords: document,ocr,recognition,yolo
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.9
+Requires-Dist: easyocr>=1.7
+Requires-Dist: numpy>=1.24
+Requires-Dist: opencv-python>=4.8
+Requires-Dist: requests>=2.28
+Requires-Dist: torch>=2.0
+Requires-Dist: torchvision>=0.15
+Requires-Dist: tqdm>=4.65
+Requires-Dist: ultralytics>=8.0
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+Заглушка

docreader_ocr-0.1.2.dist-info/RECORD

@@ -0,0 +1,21 @@
+docreader/__init__.py,sha256=be9yeILVnnzU_lYW-11JKMJQIkr5LV_nib-AoxUTj54,515
+docreader/config.py,sha256=V-ItUDeZyOuZ_2U9R_OQSYxebyfRFPLQgUCHFLBAxS8,1535
+docreader/hub.py,sha256=ko5DMLA0r8vL0S_A6g1qjjKBa_zMxJcko62NwfRCes4,6005
+docreader/pipeline.py,sha256=eVA0mfimqY7bZ4SnUyagRvxpAw8y7Osbqwg9nXS3dTw,8430
+docreader/schemas.py,sha256=McwEhIkCnX39VLGHkgHeZsTWdNo6AmRH9dscYzK9Ebw,1362
+docreader/utils.py,sha256=z9Fogt7GCTobg-f6MVP0cOQeudKrYDvnTlPpIVYI7_A,1356
+docreader/classifier/__init__.py,sha256=GGgYZLonTMb54gvwvYTyQXdhh4KRc9-E0flOewjO8sE,171
+docreader/classifier/base.py,sha256=atINqf_4EugRT5FdE0_GX-R-8GA4T0pwWpxW2aAmb8U,860
+docreader/classifier/mobilenet.py,sha256=t8Q_icYaidmRsZAA_52AFaq-eMURj1Y89meFOeUQGaQ,2634
+docreader/detector/__init__.py,sha256=eIOSsY4dEaVxkiJ0ce4SmZ961kXhocHe9va4K9597-Q,178
+docreader/detector/base.py,sha256=SyxPXeTfHFxW7ftjCPD3uGgWoryYDMvMvqXgZCslzQc,1114
+docreader/detector/yolo_obb.py,sha256=NjMnSk_96qEZcYDuf8-vu1t-X6EzDK55d3YIS2BCgHg,1949
+docreader/ocr/__init__.py,sha256=LFLTtNZp0HjV3Am-jeoHzFqmZ6HC1XW3uUGJJ9jeB3A,172
+docreader/ocr/base.py,sha256=uFcO3nSg7z0vQBeHy8A_zKVwSz8Mkurs6AAq8qCGB04,932
+docreader/ocr/easyocr_engine.py,sha256=sjBk_5UZkayf58Jo80PIyv-Fw7Tf1djYuk9LkWHMyiY,2383
+docreader/preprocessing/__init__.py,sha256=59yoWf2Q23nKRT5UXoSIkkdh0WXRSpEwdE1lgdyEHcY,123
+docreader/preprocessing/geometry.py,sha256=c-GIgf_dpicYk4YiVcPIBo3nTyU-ZAZ1wJe7VEXX0hA,3252
+docreader_ocr-0.1.2.dist-info/METADATA,sha256=Eja4nWkSZit8OBtw2esThFP8StFsdQxRLwt6PWitCfk,1299
+docreader_ocr-0.1.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+docreader_ocr-0.1.2.dist-info/licenses/LICENSE,sha256=kts17v8HVwDuR6bfFvhtVc-UyGij5ZOrp3MkOLru-oA,1130
+docreader_ocr-0.1.2.dist-info/RECORD,,

docreader_ocr-0.1.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

docreader_ocr-0.1.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikhail Kardash, Ruslan Abzelilov, Ekaterina Karmanova
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.