doctr.io¶

The io module enables users to easily access content from documents and export analysis results to structured formats.

Document structure¶

Structural organization of the documents.

Word¶

A Word is an uninterrupted sequence of characters.

class doctr.io.Word(value: str, confidence: float, geometry: tuple[tuple[float, float], tuple[float, float]] | ndarray, objectness_score: float, crop_orientation: dict[str, Any])[source]¶

Implements a word element

Parameters:

value – the text string of the word
confidence – the confidence associated with the text prediction
geometry – bounding box of the word in format ((xmin, ymin), (xmax, ymax)) where coordinates are relative to the page’s size
objectness_score – the objectness score of the detection
crop_orientation – the general orientation of the crop in degrees and its confidence

Prediction¶

A Prediction is a Word with an additional crop orientation field indicating the detected text rotation angle.

class doctr.io.Prediction(value: str, confidence: float, geometry: tuple[tuple[float, float], tuple[float, float]] | ndarray, objectness_score: float, crop_orientation: dict[str, Any])[source]¶: Implements a prediction element

Line¶

A Line is a collection of Words aligned spatially and meant to be read together (on a two-column page, on the same horizontal, we will consider that there are two Lines).

class doctr.io.Line(words: list[Word], geometry: tuple[tuple[float, float], tuple[float, float]] | ndarray | None = None, objectness_score: float | None = None)[source]¶

Implements a line element as a collection of words

Parameters:

words – list of word elements
geometry – bounding box of the word in format ((xmin, ymin), (xmax, ymax)) where coordinates are relative to the page’s size. If not specified, it will be resolved by default to the smallest bounding box enclosing all words in it.

Artefact¶

An Artefact is a non-textual element (e.g. QR code, picture, chart, signature, logo, etc.).

class doctr.io.Artefact(artefact_type: str, confidence: float, geometry: tuple[tuple[float, float], tuple[float, float]])[source]¶

Implements a non-textual element

Parameters:

artefact_type – the type of artefact
confidence – the confidence of the type prediction
geometry – bounding box of the word in format ((xmin, ymin), (xmax, ymax)) where coordinates are relative to the page’s size.

LayoutElement¶

A LayoutElement is a region predicted by a layout detection model (e.g. Title, Text, Table, Page-header, Page-footer). Layout regions are attached to a Page when the ocr_predictor / kie_predictor is run with detect_layout=True.

class doctr.io.LayoutElement(layout_type: str, confidence: float, geometry: tuple[tuple[float, float], tuple[float, float]] | ndarray)[source]¶

Implements a layout region predicted by a layout detection model

Parameters:

layout_type – the predicted region class (e.g. ‘Title’, ‘Text’, ‘Table’, ‘Page-header’)
confidence – the confidence of the region prediction
geometry – bounding box of the word in format ((xmin, ymin), (xmax, ymax)) where coordinates are relative to the page’s size

Block¶

A Block is a collection of Lines (e.g. an address written on several lines) and Artefacts (e.g. a graph with its title underneath).

class doctr.io.Block(lines: list[Line] = [], artefacts: list[Artefact] = [], geometry: tuple[tuple[float, float], tuple[float, float]] | ndarray | None = None, objectness_score: float | None = None)[source]¶

Implements a block element as a collection of lines and artefacts

Parameters:

lines – list of line elements
artefacts – list of artefacts
geometry – bounding box of the word in format ((xmin, ymin), (xmax, ymax)) where coordinates are relative to the page’s size. If not specified, it will be resolved by default to the smallest bounding box enclosing all lines and artefacts in it.

Page¶

A Page is a collection of Blocks that were on the same physical page.

class doctr.io.Page(page: ndarray, blocks: list[Block], page_idx: int, dimensions: tuple[int, int], orientation: dict[str, Any] | None = None, language: dict[str, Any] | None = None, layout: list[LayoutElement] | None = None, tables: list[Table] | None = None)[source]¶

Implements a page element as a collection of blocks

Parameters:

page – image encoded as a numpy array in uint8
blocks – list of block elements
page_idx – the index of the page in the input raw document
dimensions – the page size in pixels in format (height, width)
orientation – a dictionary with the value of the rotation angle in degress and confidence of the prediction
language – a dictionary with the language value and confidence of the prediction
layout – optional list of layout regions detected on the page
tables – optional list of tables recognized on the page. Words assigned to a table are removed from blocks.

show(interactive: bool = True, preserve_aspect_ratio: bool = False, **kwargs) → None[source]¶

Overlay the result on a given image

Parameters:

interactive – whether the display should be interactive
preserve_aspect_ratio – pass True if you passed True to the predictor
**kwargs – additional keyword arguments passed to the matplotlib.pyplot.show method (e.g. display_layout=False to hide detected layout regions)

items_in_reading_order(direction: str = 'auto') → list[Block | Table]¶

Return the content of the page (blocks & tables) sorted in reading order.

Parameters:: direction – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’
Returns:: list of blocks & tables in reading order

export_as_markdown(direction: str = 'auto', escape: bool = True, include_furniture: bool = True) → str¶

Export the page as Markdown, with its content sorted in reading order.

Parameters:

direction – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’
escape – whether the characters carrying a structural meaning in Markdown should be escaped
include_furniture – whether page headers, page footers and footnotes should be included

Returns:

a Markdown string

export_as_asciidoc(direction: str = 'auto', escape: bool = True, include_furniture: bool = True) → str¶

Export the page as AsciiDoc, with its content sorted in reading order.

Parameters:

direction – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’
escape – whether the characters and line markers carrying a structural meaning in AsciiDoc should be escaped
include_furniture – whether page headers, page footers and footnotes should be included

Returns:

an AsciiDoc string

export_as_html(direction: str = 'auto', include_furniture: bool = True) → str¶

Export the page as semantic HTML, with its content sorted in reading order.

Parameters:

direction – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’
include_furniture – whether page headers, page footers and footnotes should be included

Returns:

an HTML string

export_as_xml(file_title: str = 'docTR - XML export (hOCR)', direction: str = 'auto', reading_order: bool = True) → tuple[bytes, ElementTree]¶

Export the page as XML (hOCR-format), with its content sorted in reading order convention: https://github.com/kba/hocr-spec/blob/master/1.2/spec.md

Parameters:

file_title – the title of the XML file
direction – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’
reading_order – whether the content should be linearized in reading order

Returns:

a tuple of the XML byte string, and its ElementTree

export(reading_order: bool = True) → dict[str, Any]¶

Export the page into a nested dict, with its content sorted in reading order.

Parameters:: reading_order – whether the blocks should be linearized in reading order, exactly like the Markdown / HTML / AsciiDoc / hOCR exports. Pass False to serialize page.blocks as stored.
Returns:: a JSON-serializable dict

render(block_break: str = '\n\n', direction: str = 'auto', include_furniture: bool = True) → str¶

Renders the full text of the page, with its content sorted in reading order.

Parameters:

block_break – the string inserted between two blocks
direction – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’
include_furniture – whether page headers, page footers and footnotes should be included

Returns:

the text of the page

export_as(format: str, **kwargs: Any) → Any¶

Export the page in the requested format.

Parameters:

format – one of ‘markdown’/’md’, ‘asciidoc’/’adoc’, ‘html’, ‘text’/’txt’, ‘json’/’dict’, ‘xml’/’hocr’
**kwargs – additional keyword arguments passed to the format-specific export method

Returns:

the exported page

KIEPage¶

A KIEPage is returned by the kie_predictor. It groups predictions by semantic class rather than by spatial layout.

class doctr.io.KIEPage(page: ndarray, predictions: dict[str, list[Prediction]], page_idx: int, dimensions: tuple[int, int], orientation: dict[str, Any] | None = None, language: dict[str, Any] | None = None, layout: list[LayoutElement] | None = None)[source]¶

Implements a KIE page element as a collection of predictions

Parameters:

predictions – Dictionary with list of block elements for each detection class
page – image encoded as a numpy array in uint8
page_idx – the index of the page in the input raw document
dimensions – the page size in pixels in format (height, width)
orientation – a dictionary with the value of the rotation angle in degress and confidence of the prediction
language – a dictionary with the language value and confidence of the prediction
layout – optional list of layout regions detected on the page

show(interactive: bool = True, preserve_aspect_ratio: bool = False, **kwargs) → None[source]¶

Overlay the result on a given image

Parameters:

interactive – whether the display should be interactive
preserve_aspect_ratio – pass True if you passed True to the predictor
**kwargs – keyword arguments passed to the matplotlib.pyplot.show method

export_as_markdown(direction: str = 'auto', escape: bool = True) → str¶

Export the KIE page as Markdown, with the predictions of each class sorted in reading order.

Parameters:

direction – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’
escape – whether the characters carrying a structural meaning in Markdown should be escaped

Returns:

a Markdown string with one section per detection class

export_as_asciidoc(direction: str = 'auto', escape: bool = True) → str¶

Export the KIE page as AsciiDoc, with the predictions of each class sorted in reading order.

Parameters:

direction – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’
escape – whether the characters and line markers carrying a structural meaning in AsciiDoc should be escaped

Returns:

an AsciiDoc string with one section per detection class

export_as_html(direction: str = 'auto') → str¶: Export the KIE page as semantic HTML, with the predictions of each class sorted in reading order

export_as_xml(file_title: str = 'docTR - XML export (hOCR)', direction: str = 'auto', reading_order: bool = True) → tuple[bytes, ElementTree]¶

Export the page as XML (hOCR-format), with the predictions of each class in reading order convention: https://github.com/kba/hocr-spec/blob/master/1.2/spec.md

Parameters:

file_title – the title of the XML file
direction – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’
reading_order – whether the predictions of each class should be sorted in reading order

Returns:

a tuple of the XML byte string, and its ElementTree

export(reading_order: bool = True) → dict[str, Any]¶

Export the KIE page into a nested dict, with the predictions of each class in reading order.

Parameters:: reading_order – whether the predictions of each class should be sorted in reading order
Returns:: a JSON-serializable dict

render(prediction_break: str = '\n\n', direction: str = 'auto') → str¶

Renders the full text of the page, with the predictions of each class sorted in reading order.

Parameters:

prediction_break – the string inserted between two predictions
direction – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’

Returns:

the text of the page, one section per detection class with its predictions in reading order

export_as(format: str, **kwargs: Any) → Any¶: Export the KIE page in the requested format (‘markdown’/’md’, ‘asciidoc’/’adoc’, ‘html’, ‘text’/’txt’, ‘json’/’dict’, ‘xml’/’hocr’).

Document¶

A Document is a collection of Pages.

class doctr.io.Document(pages: list[Page])[source]¶

Implements a document element as a collection of pages

Parameters:: pages – list of page elements

show(**kwargs) → None[source]¶: Overlay the result on a given image

export_as_markdown(page_break: str = '\n\n---\n\n', **kwargs: Any) → str¶

Export the document as Markdown, with the content of each page sorted in reading order.

Parameters:

page_break – the string inserted between two pages (a thematic break by default)
**kwargs – additional keyword arguments passed to the Page.export_as_markdown method

Returns:

a Markdown string

export_as_asciidoc(page_break: str = '\n\n<<<\n\n', **kwargs: Any) → str¶

Export the document as AsciiDoc, with the content of each page sorted in reading order.

Parameters:

page_break – the string inserted between two pages (an AsciiDoc page break by default)
**kwargs – additional keyword arguments passed to the Page.export_as_asciidoc method

Returns:

an AsciiDoc string

export_as_xml(**kwargs: Any) → list[tuple[bytes, ElementTree]]¶

Export the document as XML (hOCR-format)

Parameters:: **kwargs – additional keyword arguments passed to the XML page export
Returns:: list of tuple of (bytes, ElementTree)

export_as_html(page_break: str = '<hr>', **kwargs: Any) → str¶

Export the document as semantic HTML, with the content of each page sorted in reading order.

Parameters:

page_break – the HTML snippet inserted between two pages
**kwargs – additional keyword arguments passed to the page export

Returns:

an HTML string

export(reading_order: bool = True) → dict[str, Any]¶

Export the document into a nested dict, with the content of each page sorted in reading order.

Parameters:: reading_order – whether the content of each page should be linearized in reading order
Returns:: a JSON-serializable dict

render(page_break: str = '\n\n\n\n', **kwargs: Any) → str¶

Renders the full text of the document, with the content of each page sorted in reading order.

Parameters:

page_break – the string inserted between two pages
**kwargs – additional keyword arguments passed to the Page.render / KIEPage.render method

Returns:

the text of the document

export_as(format: str, **kwargs: Any) → Any¶: Export the document in the requested format (‘markdown’/’md’, ‘asciidoc’/’adoc’, ‘html’, ‘text’/’txt’, ‘json’/’dict’, ‘xml’/’hocr’).

KIEDocument¶

A KIEDocument is a collection of KIEPage elements, returned by the kie_predictor.

class doctr.io.KIEDocument(pages: list[KIEPage])[source]¶

Implements a document element as a collection of pages

Parameters:: pages – list of page elements

show(**kwargs) → None¶: Overlay the result on a given image

File reading¶

High-performance file reading and conversion to processable structured data.

doctr.io.read_pdf(file: str | Path | bytes, scale: int = 2, rgb_mode: bool = True, password: str | None = None, **kwargs: Any) → list[ndarray][source]¶

Read a PDF file and convert it into an image in numpy format

>>> from doctr.io import read_pdf
>>> doc = read_pdf("path/to/your/doc.pdf")

Parameters:

file – the path to the PDF file
scale – rendering scale (1 corresponds to 72dpi)
rgb_mode – if True, the output will be RGB, otherwise BGR
password – a password to unlock the document, if encrypted
**kwargs – additional parameters to pypdfium2.PdfPage.render()

Returns:

the list of pages decoded as numpy ndarray of shape H x W x C

doctr.io.read_img_as_numpy(file: str | Path | bytes, output_size: tuple[int, int] | None = None, rgb_output: bool = True) → ndarray[source]¶

Read an image file into numpy format

>>> from doctr.io import read_img_as_numpy
>>> page = read_img_as_numpy("path/to/your/doc.jpg")

Parameters:

file – the path to the image file
output_size – the expected output size of each page in format H x W
rgb_output – whether the output ndarray channel order should be RGB instead of BGR.

Returns:

the page decoded as numpy ndarray of shape H x W x 3

doctr.io.read_img_as_tensor(img_path: str | Path, dtype: dtype = torch.float32) → Tensor[source]¶

Read an image file as a PyTorch tensor

Parameters:

img_path – location of the image file
dtype – the desired data type of the output tensor. If it is float-related, values will be divided by 255.

Returns:

decoded image as a tensor

doctr.io.decode_img_as_tensor(img_content: bytes, dtype: dtype = torch.float32) → Tensor[source]¶

Read a byte stream as a PyTorch tensor

Parameters:

img_content – bytes of a decoded image
dtype – the desired data type of the output tensor. If it is float-related, values will be divided by 255.

Returns:

decoded image as a tensor

doctr.io.read_html(url: str, **kwargs: Any) → bytes[source]¶

Read a PDF file and convert it into an image in numpy format

>>> from doctr.io import read_html
>>> doc = read_html("https://www.yoursite.com")

Parameters:

url – URL of the target web page
**kwargs – keyword arguments from weasyprint.HTML

Returns:

decoded PDF file as a bytes stream

class doctr.io.DocumentFile[source]¶

Read a document from multiple extensions

classmethod from_pdf(file: str | Path | bytes, **kwargs) → list[ndarray][source]¶

Read a PDF file

>>> from doctr.io import DocumentFile
>>> doc = DocumentFile.from_pdf("path/to/your/doc.pdf")

Parameters:

file – the path to the PDF file or a binary stream
**kwargs – additional parameters to pypdfium2.PdfPage.render()

Returns:

the list of pages decoded as numpy ndarray of shape H x W x 3

classmethod from_url(url: str, **kwargs) → list[ndarray][source]¶

Interpret a web page as a PDF document

>>> from doctr.io import DocumentFile
>>> doc = DocumentFile.from_url("https://www.yoursite.com")

Parameters:

url – the URL of the target web page
**kwargs – additional parameters to pypdfium2.PdfPage.render()

Returns:

the list of pages decoded as numpy ndarray of shape H x W x 3

Read an image file (or a collection of image files) and convert it into an image in numpy format

>>> from doctr.io import DocumentFile
>>> pages = DocumentFile.from_images(["path/to/your/page1.png", "path/to/your/page2.png"])

Parameters:

files – the path to the image file or a binary stream, or a collection of those
**kwargs – additional parameters to doctr.io.image.read_img_as_numpy()

Returns:

the list of pages decoded as numpy ndarray of shape H x W x 3

Reading order¶

The reading-order-aware export of a Document / Page to Markdown, AsciiDoc, HTML, or XML is available through the export_as_markdown / export_as_asciidoc / export_as_html / export_as_xml / export_as / export / render methods documented above, which delegate to the exporters of doctr.io.exporters. The underlying ordering primitives live in doctr.models.reading_order.

Every export path shares the same linearization, so render(), export(), export_as_xml() and the Markdown / AsciiDoc / HTML exports all present the content in the same order. The result is memoized on the page, so exporting one page to several formats orders it only once.

class doctr.io.TextExporter[source]¶

Export OCR results to plain text, with the content sorted in reading order.

>>> from doctr.io import TextExporter
>>> text = TextExporter().export_page(page)

export_document(document: Any, page_break: str | None = None, **kwargs: Any) → str¶

Export a document page by page.

Parameters:

document – the document to export
page_break – the string inserted between two pages (a format-specific default when None)
**kwargs – additional keyword arguments passed to the page export

Returns:

the exported document as a string

export_kie_page(page: KIEPage, direction: str = 'auto', escape: bool = True) → str¶

Export a KIE page, with the predictions of each class sorted in reading order.

Parameters:

page – the KIE page to export
direction – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’
escape – whether the characters or markers carrying a structural meaning should be neutralized

Returns:

the exported page as a string, with one section per detection class

export_page(page: Page, direction: str = 'auto', escape: bool = True, include_furniture: bool = True, block_break: str | None = None) → str¶

Export a page, with its content sorted in reading order.

Parameters:

page – the page to export
direction – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’
escape – whether the characters or markers carrying a structural meaning should be neutralized
include_furniture – whether page headers, page footers and footnotes should be included
block_break – the string inserted between two blocks (the format-specific default when None)

Returns:

the exported page as a string

class doctr.io.MarkdownExporter[source]¶

Export OCR results to Markdown, with the content sorted in reading order.

>>> from doctr.io import MarkdownExporter
>>> markdown = MarkdownExporter().export_page(page)

export_document(document: Any, page_break: str | None = None, **kwargs: Any) → str¶

Export a document page by page.

Parameters:

document – the document to export
page_break – the string inserted between two pages (a format-specific default when None)
**kwargs – additional keyword arguments passed to the page export

Returns:

the exported document as a string

export_kie_page(page: KIEPage, direction: str = 'auto', escape: bool = True) → str¶

Export a KIE page, with the predictions of each class sorted in reading order.

Parameters:

page – the KIE page to export
direction – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’
escape – whether the characters or markers carrying a structural meaning should be neutralized

Returns:

the exported page as a string, with one section per detection class

export_page(page: Page, direction: str = 'auto', escape: bool = True, include_furniture: bool = True, block_break: str | None = None) → str¶

Export a page, with its content sorted in reading order.

Parameters:

page – the page to export
direction – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’
escape – whether the characters or markers carrying a structural meaning should be neutralized
include_furniture – whether page headers, page footers and footnotes should be included
block_break – the string inserted between two blocks (the format-specific default when None)

Returns:

the exported page as a string

class doctr.io.AsciiDocExporter[source]¶

Export OCR results to AsciiDoc, with the content sorted in reading order.

>>> from doctr.io import AsciiDocExporter
>>> asciidoc = AsciiDocExporter().export_page(page)

export_document(document: Any, page_break: str | None = None, **kwargs: Any) → str¶

Export a document page by page.

Parameters:

document – the document to export
page_break – the string inserted between two pages (a format-specific default when None)
**kwargs – additional keyword arguments passed to the page export

Returns:

the exported document as a string

export_kie_page(page: KIEPage, direction: str = 'auto', escape: bool = True) → str¶

Export a KIE page, with the predictions of each class sorted in reading order.

Parameters:

page – the KIE page to export
direction – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’
escape – whether the characters or markers carrying a structural meaning should be neutralized

Returns:

the exported page as a string, with one section per detection class

export_page(page: Page, direction: str = 'auto', escape: bool = True, include_furniture: bool = True, block_break: str | None = None) → str¶

Export a page, with its content sorted in reading order.

Parameters:

page – the page to export
direction – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’
escape – whether the characters or markers carrying a structural meaning should be neutralized
include_furniture – whether page headers, page footers and footnotes should be included
block_break – the string inserted between two blocks (the format-specific default when None)

Returns:

the exported page as a string

class doctr.io.HTMLExporter[source]¶

Export OCR results to semantic HTML, with the content sorted in reading order.

Headings map to <h1>/<h2>, list items to <ul><li>, recognized tables to <table> and paragraphs to <p> (with <br> between the visual lines of a paragraph). The output is a fragment, not a full document: it carries no doctype, <html> or charset declaration.

Warning

The recognized text is HTML-escaped by default. Passing escape=False interpolates the OCR output into the markup verbatim, so a document containing markup yields active HTML. Only disable escaping for output that is never rendered in a browser.

>>> from doctr.io import HTMLExporter
>>> html = HTMLExporter().export_page(page)

export_document(document: Any, page_break: str | None = None, **kwargs: Any) → str¶

Export a document page by page.

Parameters:

document – the document to export
page_break – the string inserted between two pages (a format-specific default when None)
**kwargs – additional keyword arguments passed to the page export

Returns:

the exported document as a string

export_kie_page(page: KIEPage, direction: str = 'auto', escape: bool = True) → str[source]¶

Export a KIE page, with the predictions of each class sorted in reading order.

Parameters:

page – the KIE page to export
direction – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’
escape – whether the characters or markers carrying a structural meaning should be neutralized

Returns:

the exported page as a string, with one section per detection class

export_page(page: Page, direction: str = 'auto', escape: bool = True, include_furniture: bool = True, block_break: str | None = None) → str[source]¶

Export a page, with its content sorted in reading order.

Parameters:

page – the page to export
direction – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’
escape – whether the characters or markers carrying a structural meaning should be neutralized
include_furniture – whether page headers, page footers and footnotes should be included
block_break – the string inserted between two blocks (the format-specific default when None)

Returns:

the exported page as a string

class doctr.io.XMLExporter[source]¶

hOCR (XML) exporter for pages, KIE pages and documents. See the hOCR 1.2 specification for the XML convention: https://github.com/kba/hocr-spec/blob/master/1.2/spec.md

>>> from doctr.io import XMLExporter
>>> xml_bytes, xml_tree = XMLExporter().export_page(page)

export_document(document: Any, **kwargs: Any) → list[tuple[bytes, ElementTree]][source]¶

Export a document as a list of hOCR pages.

Parameters:

document – the document to export
**kwargs – additional keyword arguments passed to the page export

Returns:

list of tuple of (bytes, ElementTree), one per page

export_kie_page(page: KIEPage, file_title: str = 'docTR - XML export (hOCR)', direction: str = 'auto', reading_order: bool = True) → tuple[bytes, ElementTree][source]¶

Export a KIE page as hOCR XML, with the predictions of each class sorted in reading order.

Parameters:

page – the KIE page to export
file_title – the title of the XML file
direction – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’
reading_order – whether the predictions of each class should be sorted in reading order

Returns:

a tuple of the XML byte string, and its ElementTree

export_page(page: Page, file_title: str = 'docTR - XML export (hOCR)', direction: str = 'auto', reading_order: bool = True) → tuple[bytes, ElementTree][source]¶

Export a page as hOCR XML, with its content sorted in reading order.

Parameters:

page – the page to export
file_title – the title of the XML file
direction – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’
reading_order – whether the content should be linearized in reading order. Pass False to serialize page.blocks then page.tables in their raw order.

Returns:

a tuple of the XML byte string, and its ElementTree

doctr.io.exporters.page_reading_order(page: Page, direction: str = 'auto') → tuple[list[Any], list[str | None], str][source]¶

Linearize the content of a page (blocks & tables) in reading order.

The result is memoized on the page: every exporter calls this, so a page exported to several formats (or built with keep_reading_order=True and then exported) orders its content once.

Parameters:

page – the page to linearize
direction – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’

Returns:

a tuple with the ordered items (blocks & tables), their layout label (None without layout) and the effective reading direction

doctr.io.exporters.predictions_in_reading_order(page: KIEPage, predictions: list[Any], direction: str = 'auto') → list[Any][source]¶

Sort the predictions of a single KIE detection class in reading order.

Parameters:

page – the KIE page the predictions belong to (used for its dimensions and detected language)
predictions – the predictions of one detection class
direction – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’

Returns:

the predictions, ordered logically

doctr.io.exporters.to_json_safe(value: Any) → Any[source]¶

Recursively convert NumPy containers and scalars into built-in Python types.

Parameters:: value – any exported value
Returns:: the same value with every NumPy array converted to nested tuples and every NumPy scalar to its Python equivalent