Структуры данных

Основные структуры данных для представления результатов OCR.

Модель данных

Следующая диаграмма показывает взаимосвязи между структурами данных:

        graph LR

    %% Entities
    Page[Page]
    Block[Block]
    Line[Line]
    TextSpan[TextSpan]

    %% Relations
    Page -->|"blocks: List[Block]"| Block
    Block -->|"lines: List[Line]"| Line
    Line -->|"text_spans: List[TextSpan]"| TextSpan

    %% TextSpan fields
    TextSpan --> Tpoly["polygon: List[(x, y)]<br>≥ 4 points, clockwise"]
    TextSpan --> Tdet["detection_confidence: float (0–1)"]
    TextSpan --> Ttext["text: Optional[str]"]
    TextSpan --> Trec["recognition_confidence: Optional[float] (0–1)"]
    TextSpan --> Torder["order: Optional[int]<br>assigned after sorting"]

    %% Line fields
    Line --> LineOrder["order: Optional[int]<br>assigned after sorting"]

    %% Block fields
    Block --> BlockOrder["order: Optional[int]<br>assigned after sorting"]
    Block --> FlatInput["text_spans: List[TextSpan]<br>optional flat input"]

Совместимость

Канонические имена в v0_1_11 — TextSpan и text_spans. Для кода и сервисов, которые всё ещё ориентируются на v0_1_10, Word и words остаются доступными как алиасы совместимости при импорте, валидации и доступе к атрибутам из Python.

При экспорте результатов OCR указывайте схему явно:

page.to_dict(schema="v0_1_11")
page.to_json("result.json", schema="v0_1_10")

Используйте "v0_1_10" только для потребителей старого JSON-контракта. Для новых интеграций предпочтительнее "v0_1_11".

Справочник модуля

Структуры данных для OCR рукописей.

Этот пакет содержит основные структуры данных, используемые для представления результатов OCR во всей библиотеке manuscript-ocr.

class manuscript.data.TextSpan(*args, **kwargs)[исходный код]

Базовые классы: BaseModel

Один обнаруженный или распознанный текстовый фрагмент.

TextSpan — это наименьшая OCR-область в конвейере. Она может соответствовать слову, целой текстовой строке или любому другому непрерывному текстовому сегменту, возвращённому детектором.

Параметры:

args (Any)
kwargs (Any)

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

Any

polygon

Вершины полигона (x, y), упорядоченные по часовой стрелке. Публичная модель данных поддерживает произвольные полигоны с 4 или более точками. Для четырёхугольных текстовых областей канонический порядок такой: TL -> TR -> BR -> BL (верхний левый, верхний правый, нижний правый, нижний левый).

тип:: List[Tuple[float, float]]

detection_confidence

Оценка уверенности детекции текста от детектора (от 0.0 до 1.0).

тип:: float

text

Распознанное текстовое содержимое (заполняется OCR-конвейером). None, если выполнялась только детекция.

тип:: str, необязательный

recognition_confidence

Оценка уверенности распознавания текста от распознавателя (от 0.0 до 1.0). None, если выполнялась только детекция.

тип:: float, необязательный

order

Позиция текстового фрагмента внутри строки после сортировки. None до сортировки.

тип:: int, необязательный

Примеры

>>> text_span = TextSpan(
...     polygon=[(10, 20), (100, 20), (100, 40), (10, 40)],
...     detection_confidence=0.95,
...     text="Hello",
...     recognition_confidence=0.98
... )
>>> print(text_span.text)
Hello

Методы

__call__(*args, **kwargs)

Вызов объекта как функции.

detection_confidence
model_config
order
polygon
recognition_confidence
text

detection_confidence: float = Ellipsis

order: int | None = None

polygon: List[Tuple[float, float]] = Ellipsis

recognition_confidence: float | None = None

text: str | None = None

class manuscript.data.Line(*args, **kwargs)[исходный код]

Базовые классы: BaseModel

Одна текстовая строка, содержащая один или несколько текстовых фрагментов.

text_spans

Список текстовых фрагментов в строке.

тип:: List[TextSpan]

order

Позиция строки внутри блока или страницы после сортировки. None до сортировки.

тип:: int, необязательный

Примеры

>>> line = Line(text_spans=[
...     TextSpan(
...         polygon=[(10, 20), (50, 20), (50, 40), (10, 40)],
...         detection_confidence=0.95,
...         text="Hello",
...     ),
...     TextSpan(
...         polygon=[(60, 20), (110, 20), (110, 40), (60, 40)],
...         detection_confidence=0.97,
...         text="World",
...     ),
... ])
>>> print(len(line.text_spans))
2

Атрибуты:

words: Алиас обратной совместимости для text_spans.

Параметры:

args (Any)
kwargs (Any)

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

Any

Методы

__call__(*args, **kwargs)

Вызов объекта как функции.

model_config
order
text_spans

order: int | None = None

property words: List[TextSpan]: Алиас обратной совместимости для text_spans.

class manuscript.data.Block(*args, **kwargs)[исходный код]

Базовые классы: BaseModel

Логический текстовый блок (например, абзац или колонка).

lines

Список текстовых строк в блоке.

тип:: List[Line]

text_spans

Необязательный плоский список текстовых фрагментов, используемый как сокращённый вход. Если lines пуст, а text_spans переданы, они оборачиваются в одну строку.

тип:: List[TextSpan], необязательный

order

Позиция блока в порядке чтения после сортировки. None до сортировки.

тип:: int, необязательный

Примеры

>>> block = Block(lines=[
...     Line(text_spans=[
...         TextSpan(
...             polygon=[(10, 20), (50, 20), (50, 40), (10, 40)],
...             detection_confidence=0.95,
...             text="Line 1",
...         )
...     ]),
...     Line(text_spans=[
...         TextSpan(
...             polygon=[(10, 50), (50, 50), (50, 70), (10, 70)],
...             detection_confidence=0.97,
...             text="Line 2",
...         )
...     ]),
... ])
>>> print(len(block.lines))
2

Атрибуты:

words: Алиас обратной совместимости для плоского входа text_spans.

Методы

__call__(*args, **kwargs)

Вызов объекта как функции.

lines
model_config
order
text_spans

__init__(**data)[исходный код]: Инициализирует Block, сводя плоский список text_spans к одной строке.

order: int | None = None

property words: List[TextSpan]: Алиас обратной совместимости для плоского входа text_spans.

class manuscript.data.Page(*args, **kwargs)[исходный код]

Базовые классы: BaseModel

Страница документа, содержащая текстовые блоки.

Полную визуальную диаграмму модели данных см. в файле DATA_MODEL.md, расположенном в том же каталоге модуля.

Параметры:

args (Any)
kwargs (Any)

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

Any

blocks

Список текстовых блоков на странице.

тип:: List[Block]

Примеры

>>> page = Page(blocks=[
...     Block(lines=[
...         Line(text_spans=[
...             TextSpan(
...                 polygon=[(10, 20), (50, 20), (50, 40), (10, 40)],
...                 detection_confidence=0.95,
...                 text="Hello",
...             )
...         ])
...     ])
... ])
>>> print(len(page.blocks))
1

Методы

`__call__`(args, *kwargs)	Вызов объекта как функции.
`from_json`(source)	Загрузить Page из JSON-файла или строки.
`to_dict`([schema])	Экспортирует Page в обычный словарь Python.
`to_json`([path, indent, schema])	Экспорт Page в JSON.

model_config

classmethod from_json(source)[исходный код]

Загрузить Page из JSON-файла или строки.

Параметры:: source (str or Path) – Путь к JSON-файлу или JSON-строка.
Результат:: Загруженный объект Page.
Тип результата:: Page

Примеры

>>> page = Page.from_json("result.json")
>>> page = Page.from_json('{"blocks": [...]}')

to_dict(schema='v0_1_11')[исходный код]

Экспортирует Page в обычный словарь Python.

Параметры:: schema ({"v0_1_11", "v0_1_10"}, optional) – Версия выходной схемы. По умолчанию "v0_1_11".
Тип результата:: Dict[str, Any]

to_json(path=None, indent=2, schema='v0_1_11')[исходный код]

Экспорт Page в JSON.

Параметры:

path (str or Path, optional) – Если указан, сохраняет JSON в файл.
indent (int, optional) – Отступ JSON. По умолчанию 2.
schema ({"v0_1_11", "v0_1_10"}, optional) – Версия выходной схемы. По умолчанию "v0_1_11".

Результат:

Строковое представление JSON.

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

str

Примеры

>>> page.to_json("result.json")  # save to file
>>> json_str = page.to_json()    # get as string
>>> legacy_json = page.to_json(schema="v0_1_10")

blocks: List[Block]