Утилиты

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

Модуль также включает хелперы для создания объектов Page без запуска полноценного пайплайна:

• create_page_from_text — создание Page из текста; удобно для тестирования корректоров и других компонентов обработки текста.

• create_page_from_image — оборачивает одно изображение или кроп в Page с одним TextSpan, покрывающим всё изображение. Принимает также последовательность кропов и строит синтетическую страницу для прямого инференса распознавателя через API стадии 0.1.11+.

Общие утилиты для 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 – Если байты не могут быть декодированы в изображение.

Примеры

>>> img = read_image("path/to/image.jpg")
>>> img.shape
(480, 640, 3)

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

>>> pil_img = Image.open("image.jpg")
>>> img = read_image(pil_img)

>>> img = read_image(existing_array)

manuscript.utils.create_page_from_text(lines, confidence=1.0)

Создать объект Page из списка текстовых строк.

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

Каждая строка превращается в объект Line, где text span-ы формируются по разделению на пробельные символы. Для совместимости со структурами данных им назначаются фиктивные координаты полигона.

Параметры:

• lines (List[str]) – Список текстовых строк. Каждая строка будет разделена на text span-ы.

• confidence (float, optional) – Уровень уверенности, назначаемый всем text span-ам. По умолчанию 1.0.

Результат:

Объект Page с одним Block, содержащим переданные строки.

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

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].text_spans[0].text
'Hello'
>>> len(page.blocks[0].lines)
2

Использование с корректором:

>>> from manuscript.correctors import CharLM
>>> from manuscript.utils import create_page_from_text
>>>
>>> page = create_page_from_text(["Привѣтъ міръ"])
>>> corrector = CharLM()
>>> corrected = corrector.predict(page)
>>> for line in corrected.blocks[0].lines:
...     print(" ".join(span.text for span in line.text_spans))

manuscript.utils.create_page_from_image(image, confidence=1.0, gap=8, return_image=False)

Создать объект Page, оборачивающий одно или несколько изображений либо текстовых кропов.

Эта утилита полезна, когда распознаватель ожидает stage API версии 0.1.11+ (predict(page, image=...) -> Page), но нужно выполнить инференс на одном или нескольких заранее вырезанных изображениях без детектора. Для одного изображения функция создаёт один блок, одну строку и один TextSpan, покрывающий всё изображение. Для нескольких изображений кропы вертикально складываются в синтетическую страницу, и каждый из них становится отдельной строкой с одним TextSpan.

Параметры:

• image (str, Path, bytes, numpy.ndarray, PIL.Image, or sequence thereof) – Источник изображения, поддерживаемый read_image().

• confidence (float, optional) – Уверенность детекции, назначаемая созданному text span. По умолчанию 1.0.

• gap (int, optional) – Вертикальный промежуток в пикселях между кропами при передаче последовательности изображений. По умолчанию 8.

• return_image (bool, optional) – Если True, дополнительно возвращает нормализованное RGB-изображение, соответствующее созданному Page. Особенно полезно, когда image — последовательность и строится синтетическое изображение страницы. По умолчанию False.

Результат:

Объект Page с одним блоком, одной строкой и одним text span, покрывающим всё изображение. Если return_image=True, дополнительно возвращается RGB-изображение, использованное для построения страницы.

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

Page or tuple of (Page, numpy.ndarray)

Примеры

>>> from manuscript.utils import create_page_from_image
>>> page = create_page_from_image("crop1.png")
>>> span = page.blocks[0].lines[0].text_spans[0]
>>> span.polygon
[(0.0, 0.0), (120.0, 0.0), (120.0, 32.0), (0.0, 32.0)]

Использование с распознавателем:

>>> from manuscript.recognizers import TRBA
>>> page = create_page_from_image("crop1.png")
>>> recognizer = TRBA()
>>> result_page = recognizer.predict(page, image="crop1.png")
>>> result_page.blocks[0].lines[0].text_spans[0].text
'example'

Использование с несколькими кропами:

>>> page, composed_image = create_page_from_image(
...     ["crop1.png", "crop2.png"],
...     return_image=True,
... )
>>> recognizer = TRBA()
>>> result_page = recognizer.predict(page, image=composed_image)

manuscript.utils.visualize_page(image, page, color=(0, 255, 0), thickness=4, 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 с обнаруженными text span-ами и блоками.

Эта функция рисует все text span-ы из структуры 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, содержащий обнаруженные блоки и text span-ы.

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

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

• show_order (bool, default=True) – Если True, раскрашивает разные текстовые строки в разные цвета и показывает полупрозрачные границы блоков с отдельным цветом для каждого блока.

• show_lines (bool, default=False) – Если True и show_order=True, рисует соединяющие линии между соседними text span-ами, показывая последовательность чтения.

• show_numbers (bool, default=False) – Если True и show_order=True, отображает нумерованные маркеры на каждом text span-е, показывая порядок чтения.

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

• 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()
>>> page = detector.predict("document.jpg")
>>> # Can pass path directly
>>> vis = visualize_page("document.jpg", 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,
...     page,
...     show_order=True,
...     color=(255, 0, 0),
...     thickness=3
... )

Показ соединяющих линий и номеров между text span-ами.

>>> vis = visualize_page(
...     "document.jpg",
...     page,
...     show_order=True,
...     show_lines=True,
...     show_numbers=True
... )

manuscript.utils.organize_page(page, max_splits=10, use_columns=True)

Совместимый обёртчик вокруг layout-модели SimpleSorting.

Параметры:

• page (Page) – Входная страница с обнаруженными text span-ами.

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

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

Результат:

Организованная страница.

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

Page

manuscript.utils.crop_axis_aligned(image, polygon, pad=0.0)

Вырезает выровненный по осям прямоугольник, охватывающий полигон.

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

Optional[ndarray]

Параметры:

• image (numpy.ndarray)

• polygon (numpy.ndarray | Tuple[Tuple[float, float], ...])

• pad (float)

manuscript.utils.crop_polygon_mask(image, polygon, pad=0.0, background=255)

Вырезает ограничивающий прямоугольник полигона и маскирует пиксели за пределами полигона.

Работает с произвольными полигонами формы (N, 2).

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

Optional[ndarray]

Параметры:

• image (numpy.ndarray)

• polygon (numpy.ndarray | Tuple[Tuple[float, float], ...])

• pad (float)

• background (int)

manuscript.utils.merge_polygons(polygons, method='bbox')

Объединяет несколько полигонов в один.

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

Optional[List[Tuple[float, float]]]

Параметры:

• polygons (Sequence[numpy.ndarray | Tuple[Tuple[float, float], ...]])

• method (str)

manuscript.utils.order_quad_points(points)

Упорядочивает ровно 4 точки полигона в порядке: верхний левый, верхний правый, нижний правый, нижний левый.

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

ndarray

Параметры:

points (numpy.ndarray | Tuple[Tuple[float, float], ...])

manuscript.utils.polygon_to_bbox(polygon, image_shape=None, pad=0.0)

Преобразует полигон с произвольным числом вершин в обрезанный ограничивающий прямоугольник, выровненный по осям.

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

Optional[Tuple[int, int, int, int]]

Параметры:

• polygon (numpy.ndarray | Tuple[Tuple[float, float], ...])

• image_shape (Tuple[int, ...] | None)

• pad (float)

manuscript.utils.warp_quad(image, polygon, output_size=None, background=255)

Применяет перспективное преобразование к четырёхугольному полигону и возвращает выпрямленный кроп.

Функция намеренно предназначена только для четырёхугольников. Для полигонов с другим числом вершин возвращает None, чтобы вызывающий код мог выбрать запасную стратегию.

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

Optional[ndarray]

Параметры:

• image (numpy.ndarray)

• polygon (numpy.ndarray | Tuple[Tuple[float, float], ...])

• output_size (Tuple[int, int] | None)

• background (int)

manuscript.utils.merge_text_spans(text_spans, method='bbox')

Объединить несколько объектов TextSpan в один более широкий TextSpan.

Параметры:

• text_spans (sequence of TextSpan) – Входные text span-ы для объединения.

• method ({"bbox", "convex_hull"}, optional) – Стратегия объединения полигонов. "bbox" строит выровненный по осям прямоугольник, охватывающий все полигоны span-ов. "convex_hull" строит выпуклую оболочку вокруг всех вершин полигонов. По умолчанию "bbox".

Результат:

Объединённый text span или None, если text_spans пустой.

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

TextSpan or None

manuscript.utils.collapse_line_text_spans(line, method='bbox')

Свернуть все text span-ы внутри строки в один text span.

Параметры:

• line (Line) – Входная строка.

• method ({"bbox", "convex_hull"}, optional) – Стратегия объединения полигонов. По умолчанию "bbox".

Результат:

Новая строка, содержащая один объединённый text span или пустой список span-ов.

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

Line

manuscript.utils.collapse_block_text_spans(block, method='bbox')

Свернуть все text span-ы внутри блока в одну строку с одним text span-ом.

Параметры:

• block (Block) – Входной блок.

• method ({"bbox", "convex_hull"}, optional) – Стратегия объединения полигонов. По умолчанию "bbox".

Результат:

Новый блок, содержащий одну свёрнутую строку.

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

Block

manuscript.utils.collapse_page_text_spans(page, level='line', method='bbox')

Свести узкую OCR-структуру к более широким span-ам уровня строки или блока.

Параметры:

• page (Page) – Входная страница.

• level ({"line", "block"}, optional) – Целевой уровень свёртки. "line" сохраняет исходную структуру блоков и строк, заменяя каждую строку одним объединённым text span-ом. "block" заменяет каждый блок одной строкой с одним объединённым text span-ом. По умолчанию "line".

• method ({"bbox", "convex_hull"}, optional) – Стратегия объединения полигонов. По умолчанию "bbox".

Результат:

Свёрнутая страница.

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

Page

manuscript.utils.set_seed(seed=42)

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

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

None

Параметры:

seed (int)