Утилиты

Изображения и тестовые страницы

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

Читает изображение из файла, массива, байтов или объекта PIL.

Параметры:

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_image(image, confidence=1.0, gap=8, return_image=False, *, region_type='word')[исходный код]

Создаёт Page, в котором каждому фрагменту изображения соответствует отдельный текстовый регион.

Если изображений несколько, они размещаются сверху вниз в исходном порядке на белом RGB-холсте. По умолчанию region_type равен word (для TRBA). Для строк PPOCRRec/TrOCR укажите line, для блока текста — block. Размеры Page и координаты полигонов задаются относительно полученного холста. При передаче одного файла сохраняется file_name.

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

Union[Page, Tuple[Page, ndarray]]

Параметры:

image (str | Path | bytes | numpy.ndarray | Image | Sequence[str | Path | bytes | numpy.ndarray | Image])
confidence (float)
gap (int)
return_image (bool)
region_type (str)

>>> page, pixels = create_page_from_image(np.zeros((32, 100, 3), np.uint8),
...                                      region_type="line", return_image=True)
>>> page.children[0].type
'line'
>>> (page.image_width, page.image_height)
(100, 32)

manuscript.utils.create_page_from_text(lines, confidence=1.0)[исходный код]

Создать дерево блок → строки → слова с искусственными пиксельными координатами.

Принимает список строк или многострочный текст. Слова разделяются по пробельным символам. Пустые строки оставляют промежутки по вертикали, но не создают пустых регионов. Условные координаты позволяют проверять обработку текста без запуска OCR.

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

Page

Параметры:

lines (str | Sequence[str])
confidence (float)

>>> page = create_page_from_text(["Hello world"])
>>> page.children[0].children[0].children[0].text
'Hello'

Группировка и упорядочивание

manuscript.utils.group_regions(regions, *, type, geometry='bbox', concavity=0.3)[исходный код]

Группирует соседние текстовые регионы в новый регион более высокого уровня.

По умолчанию используется ограничивающий прямоугольник. Другие режимы геометрии: convex_hull, concave_hull и None. Функция получает копии списков полигонов и возвращает полигон или None. Для concave_hull параметр concavity соответствует ratio в Shapely: 0 даёт наиболее вогнутый контур, 1 — выпуклую оболочку (нужны Shapely 2 / GEOS 3.11). Порядок дочерних элементов соответствует входу. Группа заменяет первого выбранного соседа в списке родителя. Отсоединённые регионы тоже можно группировать. Все проверки и вычисления геометрии выполняются до изменения связей дерева.

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

TextRegion

Параметры:

regions (Sequence[TextRegion])
type (str)
geometry (str | Callable | None)
concavity (float)

manuscript.utils.organize_page(page, max_splits=10, use_columns=True)[исходный код]

Обёртка для SimpleSorting, сохранённая для совместимости.

Параметры:

page (Page) – Страница с обнаруженными текстовыми регионами.
max_splits (int, optional) – Максимальное число попыток разбиения на колонки. По умолчанию 10.
use_columns (bool, optional) – Если True, сначала выполняет разбиение на колонки, а затем группировку по строкам. По умолчанию True.

Результат:

Страница с упорядоченными регионами.

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

Page

Свёртка текстовых регионов

manuscript.utils.merge_text_spans(text_spans, method='bbox', *, type='word')[исходный код]

Объединить отсоединённые текстовые регионы в один; исходные объекты не меняются.

Тип результата:: Optional[TextRegion]
Параметры:: text_spans (Sequence[TextRegion])

manuscript.utils.collapse_line_text_spans(line, method='bbox')[исходный код]

manuscript.utils.collapse_block_text_spans(block, method='bbox')[исходный код]

manuscript.utils.collapse_page_text_spans(page, level='line', method='bbox')[исходный код]

Свернуть подходящие текстовые контейнеры, сохранив остальные узлы дерева.

Тип результата:: Page
Параметры:: page (Page)

Геометрия

manuscript.utils.polygon_to_bbox(polygon, image_shape=None, pad=0.0)[исходный код]

Находит ограничивающий прямоугольник полигона со сторонами вдоль осей и обрезает его по границам изображения.

Параметры:

polygon (array-like of shape (N, 2)) – Вершины полигона в координатах изображения.
image_shape (tuple, optional) – Размеры исходного изображения, по которым ограничиваются координаты.
pad (float, optional) – Дополнительный отступ в пикселях вокруг полигона. По умолчанию 0.

Результат:

Ограничивающий прямоугольник (x1, y1, x2, y2) или None, если результат недопустим.

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

tuple or None

manuscript.utils.crop_axis_aligned(image, polygon, pad=0.0)[исходный код]

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

Параметры:

image (numpy.ndarray) – Исходное изображение.
polygon (array-like of shape (N, 2)) – Вершины полигона в координатах изображения.
pad (float, optional) – Дополнительный отступ в пикселях вокруг полигона. По умолчанию 0.

Результат:

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

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

numpy.ndarray or None

manuscript.utils.crop_polygon_mask(image, polygon, pad=0.0, background=255)[исходный код]

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

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

Параметры:

image (numpy.ndarray) – Исходное изображение.
polygon (array-like of shape (N, 2)) – Вершины полигона в координатах изображения.
pad (float, optional) – Дополнительный отступ в пикселях вокруг полигона. По умолчанию 0.
background (int, optional) – Значение фоновых пикселей за пределами полигона. По умолчанию 255.

Результат:

Фрагмент с маской или None, если ограничивающий прямоугольник недопустим.

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

numpy.ndarray or None

manuscript.utils.order_quad_points(points)[исходный код]

Располагает четыре вершины полигона в порядке: верхняя левая, верхняя правая, нижняя правая, нижняя левая.

Параметры:: points (array-like of shape (4, 2)) – Вершины четырёхугольника.
Результат:: Упорядоченные вершины типа float32.
Тип результата:: numpy.ndarray
Исключение:: ValueError – Если число переданных точек не равно четырём.

manuscript.utils.warp_quad(image, polygon, output_size=None, background=255)[исходный код]

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

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

Параметры:

image (numpy.ndarray) – Исходное изображение.
polygon (array-like of shape (4, 2)) – Вершины четырёхугольника в координатах изображения.
output_size (tuple of int, optional) – Размер фрагмента (width, height). При None оценивается по рёбрам полигона.
background (int)

Результат:

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

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

numpy.ndarray or None

manuscript.utils.merge_polygons(polygons, method='bbox')[исходный код]

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

Параметры:

polygons (sequence of array-like polygons) – Входные полигоны формы (N, 2).
method ({"bbox", "convex_hull"}, optional) – Способ объединения. "bbox" возвращает выровненный по осям прямоугольник, охватывающий все точки. "convex_hull" возвращает выпуклую оболочку всех точек.

Результат:

Объединённый полигон или None, если polygons пуст.

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

list of tuple or None

Визуализация

manuscript.utils.visualize_page(image, page, thickness=3, numbers_levels=(1, 2), connections_levels=(), line_color=(255, 165, 0), number_bg=(255, 255, 255), number_color=(0, 0, 0), max_size=4096, upscale=False, show_tables=True, show_cells=True, show_cell_indices=False, show_orientation=False, show_labels=False)[исходный код]

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

Фон затемняется на 30%. Первый уровень восстанавливает исходную яркость, добавляя 15% за каждое дополнительное наложение. Чётные уровни смешивают полупрозрачные холодные цвета, различая соседние элементы. Нечётные уровни начиная с третьего осветляют накопленные цвета на 25% за наложение. Тёмные контуры толщиной три пикселя имеют общий цвет в каждом поддереве первого уровня. numbers_levels и connections_levels выбирают глубины дерева; пустые списки отключают маркеры. Номера по умолчанию показываются для первого и второго уровней. Маркеры следуют обходу в глубину среди видимых полигонов данного уровня. На одной глубине учитываются не более двух наложений. show_labels выводит исходную метку модели или тип элемента на каждом регионе.

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

Image

Параметры:

image (str | Path | numpy.ndarray | Image)
page (Page)

Вспомогательная функция обучения

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

Задаёт начальное состояние генераторов случайных чисел Python и PyTorch. Требуется PyTorch.

Функция не настраивает генератор NumPy и не гарантирует полной воспроизводимости.

Тип результата:: None
Параметры:: seed (int)