# STAGE2_RESEARCH_RESULT.md

## Результат исследования PaddleOCR 3.7.0 + Docling 2.117.0

Дата: 2026-08-03

---

## 1. PaddleOCR — возможности

Версия: **3.7.0** (июнь 2026)

**PP-StructureV3** — ключевой компонент для обработки документов:
- Преобразует PDF/изображения в структурированный **Markdown** или **JSON**
- Определяет layout страницы, reading order, таблицы, формулы
- Предоставляет **координаты** каждого элемента (текстовые блоки, ячейки таблиц, строки)
- Возвращает **confidence** для результатов OCR
- Поддерживает 100+ языков (PP-OCRv6: 50 языков в единой модели)

**PP-OCRv6** — текстовое распознавание:
- 34.5M параметров, превосходит большие VLM по точности
- 5.2× ускорение на CPU (OpenVINO)
- Детекция + распознавание текста

**Экспорт:** Markdown, JSON, DOCX

---

## 2. Docling — возможности

Версия: **2.117.0** (июль 2026), IBM Research, MIT License

**Ключевая функциональность:**
- Парсинг PDF, DOCX, PPTX, XLSX, HTML, EPUB, изображений (PNG/TIFF/JPEG)
- Layout detection, reading order, table structure, code, formulas, image classification
- Единый формат `DoclingDocument`
- Экспорт: **Markdown, HTML, JSON, DocTags, lossless JSON**
- Confidence scores (с v2.34.0): layout_score, ocr_score, parse_score, table_score

**OCR-движки (НЕТ PaddleOCR!):**
- EasyOCR, Tesseract, Tesseract CLI, RapidOCR, Nemotron OCR, OcrMac, OnnxTR

**Форматы экспорта:**

| Формат | Официально | Структура | Для LLM |
|--------|-----------|-----------|---------|
| HTML | ✅ | Полная (таблицы, изображения, заголовки) | Отлично |
| Markdown | ✅ | Хорошая (таблицы, заголовки) | Отлично |
| JSON | ✅ | Полная, lossless | Хорошо |
| DocTags | ✅ | Полная, с координатами | Средне |
| Plain Text | ❌ (через Markdown) | Базовая | Плохо |

---

## 3. Совместимость PaddleOCR + Docling

**Docling НЕ поддерживает PaddleOCR как OCR-движок** (v2.117.0). 

Доступные движки: EasyOCR, Tesseract, RapidOCR, Nemotron, OcrMac, OnnxTR.

**Вывод:** напрямую интегрировать PaddleOCR в Docling в качестве OCR-backend невозможно без форка Docling.

Альтернативы для проекта scan2html:
- **Вариант А**: Использовать **PaddleOCR PP-StructureV3** напрямую — он сам выполняет полный pipeline (OCR + структура + Markdown/JSON) — Docling не нужен
- **Вариант Б**: Использовать **Docling** со встроенным OCR (EasyOCR/RapidOCR) — HTML экспорт из коробки
- **Вариант В**: Самостоятельная генерация HTML из результатов PaddleOCR

---

## 4. Качество HTML (Docling)

Docling генерирует HTML с сохранением:
- ✅ Таблицы (включая rowspan/colspan)
- ✅ Заголовки (h1-h6)
- ✅ Списки (ul/ol)
- ✅ Изображения (встроенные base64)
- ✅ Подписи рисунков
- ✅ Формулы (MathML)
- ❗ Объединённые ячейки — зависит от качества OCR

**PaddleOCR PP-StructureV3** также сохраняет структуру в Markdown/JSON с координатами — но HTML-экспорта из коробки не предоставляет (только Markdown, JSON, DOCX).

---

## 5. Таблицы

**Docling:**
- Таблицы с поддержкой rowspan/colspan ✅
- Качество зависит от OCR-движка
- Экспорт в HTML с сохранением colspan/rowspan ✅

**PaddleOCR PP-StructureV3:**
- Таблицы с координатами ячеек ✅
- Восстановление сложных таблиц ✅
- Экспорт в Markdown (базовый) и JSON (с координатами)

---

## 6. Формулы

**Docling:**
- Распознавание формул ✅
- Экспорт в MathML ✅
- LaTeX не поддерживается в HTML (только через MathML)

**PaddleOCR PP-StructureV3:**
- Распознавание формул ✅
- Экспорт LaTeX ✅ (в Markdown/JSON)

---

## 7. OCR Confidence

**PaddleOCR:** предоставляет confidence для каждого распознанного слова/символа.

**Docling:** с v2.34.0 предоставляет:
- `layout_score` — качество детекции элементов
- `ocr_score` — качество OCR
- `parse_score` — 10-й перцентиль уверенности
- `table_score` — качество таблиц (ещё не реализовано)
- Page-level и document-level оценки

Confidence можно использовать для подсветки сомнительных мест.

---

## 8. Координаты элементов

**PaddleOCR PP-StructureV3:** ✅ Полные координаты
- Страницы ✅
- Абзацы ✅
- Таблицы + ячейки строк ✅
- Отдельные слова/символы ✅

**Docling:** координаты доступны через DoclingDocument API (bounding boxes), но в HTML экспорт не передаются.

---

## 9. Производительность

**PaddleOCR PP-StructureV3:**
- ~2-5 секунд на страницу на CPU
- RAM: ~2-4 GB для моделей
- GPU: значительное ускорение
- Пакетная обработка ✅

**Docling:**
- ~1-3 секунды на страницу на CPU (EasyOCR: >10 с)
- RAM: ~2-4 GB для моделей
- Пакетная обработка ✅
- GPU: поддерживается через PyTorch/CUDA

---

## 10. Offline-режим

**PaddleOCR:** ✅ полностью offline. Модели скачиваются один раз в `~/.paddlex/official_models/`.

**Docling:** ✅ полностью offline. Модели кешируются локально. Нет обращений к облачным сервисам. Поддерживает air-gapped environments.

---

## 11. Минимальный рабочий пример

```python
# ===== PaddleOCR PP-StructureV3: полный pipeline =====
from paddleocr import PaddleOCR

ocr = PaddleOCR(lang="en", use_structure=True)
result = ocr.predict("page.jpg")
# result содержит:
#   - markdown: структурированный Markdown
#   - json: полный JSON с координатами
#   - ocr_result: детальный OCR с confidence
#   - table_result: таблицы с ячейками
#   - layout_result: layout страницы

# ===== Docling: преобразование в HTML =====
from docling.document_converter import DocumentConverter

converter = DocumentConverter()
result = converter.convert("page.jpg")
html = result.document.export_to_html()
markdown = result.document.export_to_markdown()
json_out = result.document.export_to_dict()
confidence = result.confidence  # ConfidenceReport
```

---

## 12. Что уже реализовано библиотеками (не требует разработки)

| Функция | PaddleOCR | Docling |
|---------|-----------|---------|
| OCR текста | PP-OCRv6 | EasyOCR/Tesseract/RapidOCR |
| Layout detection | PP-StructureV3 | Встроенный DocLayNet |
| Reading order | ✅ | ✅ |
| Таблицы + ячейки | PP-StructureV3 | TableFormer |
| Формулы → LaTeX | PP-StructureV3 | Formula recognition |
| HTML экспорт | ❌ (только MD/JSON/DOCX) | ✅ |
| Markdown экспорт | ✅ | ✅ |
| JSON экспорт | ✅ | ✅ |
| DOCX экспорт | ✅ (v3.5+) | ❌ |
| Confidence scores | ✅ | ✅ |
| Координаты элементов | ✅ | ✅ |
| Пакетная обработка | ✅ | ✅ |

---

## 13. Что придётся реализовать самостоятельно

1. **Генерация HTML с координатами элементов из PaddleOCR** — если выбран PaddleOCR
2. **Подсветка сомнительных мест** — на основе confidence (любой движок)
3. **Передача confidence в HTML** — через data-атрибуты или CSS-классы
4. **Интеграция PaddleOCR + Docling** — если нужна, требует форка Docling

---

## 14. Рекомендуемая архитектура Stage 2

### Рекомендация: использовать **PaddleOCR PP-StructureV3** как основной движок

**Обоснование:**
1. PaddleOCR PP-StructureV3 сам выполняет полный pipeline: OCR + структура + таблицы + формулы + координаты
2. Docling не нужен как промежуточный слой — он не добавляет ценности при уже имеющемся PaddleOCR
3. PaddleOCR даёт более детальные координаты и confidence, чем Docling
4. Не требуется интеграция двух библиотек — снижается сложность
5. HTML-генерацию можно реализовать как отдельный модуль (`src/html/`), принимающий на вход JSON от PaddleOCR

### Pipeline Stage 2:

```
JPEG page
    ↓
PaddleOCR PP-StructureV3
    ↓
JSON (структура + координаты + confidence)
    ↓
Генератор HTML (src/html/)
    ↓
HTML с data-атрибутами (confidence, координаты)
```

### Модули для реализации:

```
src/
  split/       — разрезание (Stage 1, готово)
  preprocess/  — deskew, crop, denoise (будущие этапы)
  ocr/         — обёртка над PaddleOCR PP-StructureV3
  html/        — генерация HTML из JSON-результата OCR
  image_split.py — CLI (Stage 1)
```

---

## 15. Итоговая рекомендация

1. **Не использовать Docling** для данного проекта — он не даёт преимуществ перед PaddleOCR PP-StructureV3 и не поддерживает PaddleOCR как OCR-backend
2. **Использовать PaddleOCR PP-StructureV3** для OCR и извлечения структуры документа
3. **Реализовать HTML-генератор** (модуль `src/html/`) на основе JSON-вывода PaddleOCR
4. **Добавить confidence-подсветку** в HTML через data-атрибуты
5. **Структура проекта** уже соответствует архитектуре из `.ai/ARCHITECTURE.md`

Главная цель минимизации собственного кода достигнута: PaddleOCR PP-StructureV3 покрывает OCR, layout detection, таблицы, формулы, координаты и confidence. Собственной реализации требует только HTML-генератор и CLI-интеграция.