Утилиты

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

Общие утилиты для 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 text spans split by whitespace. Text spans are assigned dummy polygon coordinates for compatibility with the data structures.

Параметры:

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

• confidence (float, optional) – Confidence score to assign to all text spans (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].text_spans[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(span.text for span in line.text_spans))

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)

Visualize a Page object with detected text spans/blocks.

This function draws all text spans from the Page structure on the image, optionally showing reading order with numbered markers and connecting lines. When show_order=True, it also visualizes blocks with semi-transparent bounding boxes, each block having a distinct color.

Параметры:

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

• page (Page) – Page object from manuscript.data containing detected blocks/text spans.

• color (tuple of int, default=(0, 255, 0)) – RGB color for text span boundaries.

• thickness (int, default=4) – Line thickness for text span boundaries.

• 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 text spans showing the reading sequence.

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

• line_color (tuple of int, default=(255, 165, 0)) – RGB color for connecting lines between text spans.

• 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
... )

Show connecting lines and numbers between text spans:

>>> 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)

Compatibility wrapper around SimpleSorting layout model.

Параметры:

• page (Page) – Input page with detected text spans.

• max_splits (int, optional) – Maximum number of column split attempts. Default is 10.

• use_columns (bool, optional) – If True, segment into columns before line grouping. Default is True.

Результат:

Organized page.

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

Page

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

Crop an axis-aligned rectangle covering the polygon.

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

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)

Crop the polygon bounding box and mask pixels outside the polygon.

Works with arbitrary polygons of shape (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')

Merge multiple polygons into a single polygon.

Параметры:

• polygons (sequence of array-like polygons) – Input polygons with shape (N, 2).

• method ({"bbox", "convex_hull"}, optional) – Merge strategy. "bbox" returns an axis-aligned rectangle covering all points. "convex_hull" returns a convex hull over all points.

Результат:

Merged polygon, or None when polygons is empty.

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

list of tuple or None

manuscript.utils.order_quad_points(points)

Order exactly 4 polygon points as top-left, top-right, bottom-right, bottom-left.

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

ndarray

Параметры:

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

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

Convert a polygon with any number of vertices to a clipped axis-aligned bounding box.

Параметры:

• polygon (array-like of shape (N, 2)) – Polygon vertices in image coordinates.

• image_shape (tuple, optional) – Source image shape used for clipping.

• pad (float, optional) – Extra padding in pixels around the polygon. Default is 0.

Результат:

Bounding box as (x1, y1, x2, y2) or None if invalid.

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

tuple or None

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

Perspective-warp a quadrilateral polygon into a rectified crop.

This helper is intentionally quad-specific. For non-quad polygons it returns None so callers may choose a fallback strategy.

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

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')

Merge multiple TextSpan objects into a single wider TextSpan.

Параметры:

• text_spans (sequence of TextSpan) – Input text spans to merge.

• method ({"bbox", "convex_hull"}, optional) – Polygon merge strategy. "bbox" creates an axis-aligned rectangle covering all span polygons. "convex_hull" creates a convex hull around all polygon vertices. Default is "bbox".

Результат:

Merged text span, or None when text_spans is empty.

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

TextSpan or None

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

Collapse all text spans inside a line into a single text span.

Параметры:

• line (Line) – Input line.

• method ({"bbox", "convex_hull"}, optional) – Polygon merge strategy. Default is "bbox".

Результат:

New line containing one merged text span or an empty span list.

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

Line

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

Collapse all text spans inside a block into a single line with one text span.

Параметры:

• block (Block) – Input block.

• method ({"bbox", "convex_hull"}, optional) – Polygon merge strategy. Default is "bbox".

Результат:

New block containing a single collapsed line.

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

Block

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

Collapse narrow OCR structure into wider line-level or block-level spans.

Параметры:

• page (Page) – Input page.

• level ({"line", "block"}, optional) – Collapse target. "line" keeps the same block/line structure and replaces each line with one merged text span. "block" replaces each block with one line containing one merged text span. Default is "line".

• method ({"bbox", "convex_hull"}, optional) – Polygon merge strategy. Default is "bbox".

Результат:

Collapsed page.

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

Page

manuscript.utils.set_seed(seed=42)

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

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

None

Параметры:

seed (int)