Утилиты

Вспомогательные функции для обработки изображений, визуализации и других задач.

Общие утилиты для manuscript-ocr.

manuscript.utils.read_image(img_or_path)[исходный код]

Универсальное чтение изображений с поддержкой различных типов входных данных.

Параметры:

img_or_path (str, Path, bytes, np.ndarray, or PIL.Image) – Источник изображения в одном из следующих форматов: - путь к файлу (str или Path) — поддерживаются Unicode-пути (например, кириллица) - буфер байтов (например, из HTTP-ответа) - массив NumPy (уже загруженное изображение) - объект PIL Image

Результат:

RGB-изображение в виде массива NumPy с формой (H, W, 3) и типом uint8.

Тип результата:

np.ndarray

Исключение:

  • FileNotFoundError – Если файл изображения не удаётся прочитать ни с помощью OpenCV, ни с помощью PIL.

  • TypeError – Если тип входных данных не поддерживается.

  • ValueError – Если байты не могут быть декодированы в изображение.

Примеры

>>> # Read from file path (with Unicode support)
>>> img = read_image("путь/к/изображению.jpg")
>>> img.shape
(480, 640, 3)

>>> # Read from bytes
>>> with open("image.jpg", "rb") as f:
...     img = read_image(f.read())

>>> # Read from PIL Image
>>> pil_img = Image.open("image.jpg")
>>> img = read_image(pil_img)

>>> # Pass through numpy array
>>> img = read_image(existing_array)
manuscript.utils.create_page_from_text(lines, confidence=1.0)[исходный код]

Create a Page object from a list of text lines.

This utility function creates a simple Page structure from raw text, useful for testing correctors or other text processing components without requiring actual OCR detection/recognition.

Each line becomes a Line object with words split by whitespace. Words are assigned dummy polygon coordinates for compatibility with the data structures.

Параметры:

  • lines (List[str]) – List of text lines. Each line will be split into words.

  • confidence (float, optional) – Confidence score to assign to all words (default 1.0).

Результат:

Page object with one Block containing the provided lines.

Тип результата:

Page

Примеры

>>> from manuscript.utils import create_page_from_text
>>> page = create_page_from_text(["Hello world", "This is a test"])
>>> page.blocks[0].lines[0].words[0].text
'Hello'
>>> len(page.blocks[0].lines)
2

Use with corrector:

>>> from manuscript.correctors import CharLM
>>> from manuscript.utils import create_page_from_text
>>>
>>> # Create page from text with potential OCR errors
>>> page = create_page_from_text(["Привѣтъ міръ"])
>>>
>>> # Apply correction
>>> corrector = CharLM()
>>> corrected = corrector.predict(page)
>>>
>>> # Get corrected text
>>> for line in corrected.blocks[0].lines:
...     print(" ".join(w.text for w in line.words))
manuscript.utils.visualize_page(image, page, color=(0, 255, 0), thickness=2, show_order=True, show_lines=False, show_numbers=False, line_color=(255, 165, 0), number_bg=(255, 255, 255), number_color=(0, 0, 0), max_size=4096)[исходный код]

Визуализация объекта Page с обнаруженными словами и блоками.

Эта функция рисует все слова из структуры Page на изображении, при необходимости отображая порядок чтения с помощью нумерованных маркеров и соединяющих линий. При show_order=True также визуализируются блоки с полупрозрачными ограничивающими рамками, при этом каждый блок имеет свой цвет.

Параметры:

  • image (str, Path, np.ndarray, or PIL.Image) – Входное изображение. Может быть: - путь к файлу изображения (str или Path) — поддерживаются Unicode-пути - RGB-массив NumPy с формой (H, W, 3) - объект PIL Image

  • page (Page) – Объект Page из manuscript.data, содержащий обнаруженные блоки и слова.

  • color (tuple of int, default=(0, 255, 0)) – RGB-цвет для границ слов.

  • thickness (int, default=2) – Толщина линий для границ слов.

  • show_order (bool, default=True) – If True, colors different text lines with different colors and shows semi-transparent block boundaries with different colors per block.

  • show_lines (bool, default=False) – If True and show_order=True, draw connecting lines between consecutive words showing the reading sequence.

  • show_numbers (bool, default=False) – If True and show_order=True, display numbered markers on each word showing the reading order.

  • line_color (tuple of int, default=(255, 165, 0)) – RGB-цвет для соединяющих линий между словами.

  • number_bg (tuple of int, default=(255, 255, 255)) – Цвет фона для блоков с номерами порядка.

  • number_color (tuple of int, default=(0, 0, 0)) – Цвет текста для номеров порядка.

  • max_size (int or None, default=4096) – Максимальный размер большей стороны выходного изображения. Если изображение больше, оно будет пропорционально уменьшено. Установите None, чтобы сохранить исходный размер.

Результат:

Визуализированное изображение с рамками детекции и, при необходимости, аннотациями порядка чтения. При show_order=True также включает полупрозрачные границы блоков.

Тип результата:

PIL.Image.Image

Примеры

Базовая визуализация без порядка чтения:

>>> from manuscript import EAST
>>> from manuscript.utils import visualize_page
>>> detector = EAST()
>>> result = detector.predict("document.jpg")
>>> # Can pass path directly
>>> vis = visualize_page("document.jpg", result["page"])
>>> vis.save("output.jpg")

Визуализация с порядком чтения и границами блоков:

>>> # Can also use numpy array or PIL Image
>>> from manuscript.utils import read_image
>>> img = read_image("document.jpg")
>>> vis = visualize_page(
...     img,
...     result["page"],
...     show_order=True,
...     color=(255, 0, 0),
...     thickness=3
... )

Show connecting lines and numbers between words:

>>> vis = visualize_page(
...     "document.jpg",
...     result["page"],
...     show_order=True,
...     show_lines=True,
...     show_numbers=True
... )
manuscript.utils.organize_page(page, max_splits=10, use_columns=True)[исходный код]

Организация слов на странице Page в структурированные блоки, строки и порядок чтения.

Принимает Page с неорганизованными словами и возвращает новый Page, где: - слова сгруппированы в колонки (Blocks) - каждый блок содержит строки слов - слова внутри строк упорядочены слева направо - строки внутри блоков упорядочены сверху вниз - блоки упорядочены слева направо (для колонок)

Параметры:

  • page (Page) – Входной объект Page. Может содержать: - слова в неструктурированных блоках/строках - прямой список слов без корректной организации

  • max_splits (int, optional) – Максимальное количество попыток разбиения на колонки при сегментации. Большие значения позволяют обнаруживать больше колонок. По умолчанию 10.

  • use_columns (bool, optional) – Если True, сегментирует страницу на колонки (отдельные блоки). Если False, рассматривает всю страницу как одну колонку. По умолчанию True.

Результат:

Новый объект Page с организованными блоками, строками и установленным порядком чтения.

Тип результата:

Page

Примеры

>>> from manuscript.detectors import EAST
>>> from manuscript.utils import organize_page
>>>
>>> detector = EAST()
>>> result = detector.predict("image.jpg", sort_reading_order=False)
>>> page = result["page"]
>>>
>>> # Organize into structured reading order
>>> organized_page = organize_page(page, max_splits=5)
>>>
>>> # Access first word in first line of first block
>>> first_word = organized_page.blocks[0].lines[0].words[0]
>>> print(f"Word order: {first_word.order}")

Заметки

Эта функция извлекает все слова из входного Page (независимо от их текущей организации), преобразует их в ограничивающие прямоугольники, выполняет сегментацию на колонки и сортировку строк, а затем заново строит чистую структуру Page.

Функция сохраняет все атрибуты Word (полигон, уверенность, текст и т. д.), обновляя при этом поле order, отвечающее за последовательность чтения.

manuscript.utils.set_seed(seed=42)[исходный код]

Установка случайного зерна для воспроизводимости в random, NumPy и PyTorch.

Тип результата:

None

Параметры:

seed (int)