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 Word(value, confidence, geometry, objectness_score, crop_orientation)

Implements a word element

Parameters:

• value (str) – the text string of the word

• confidence (float) – the confidence associated with the text prediction

• geometry (tuple[tuple[float, float], tuple[float, float]] | ndarray) – bounding box of the word in format ((xmin, ymin), (xmax, ymax)) where coordinates are relative to the page’s size

• objectness_score (float) – the objectness score of the detection

• crop_orientation (dict[str, Any]) – 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 Prediction(value, confidence, geometry, objectness_score, crop_orientation)

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 Line(words, geometry=None, objectness_score=None)

Implements a line element as a collection of words

Parameters:

• words (list[Word]) – list of word elements

• geometry (tuple[tuple[float, float], tuple[float, float]] | ndarray | None) – 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 Artefact(artefact_type, confidence, geometry)

Implements a non-textual element

Parameters:

• artefact_type (str) – the type of artefact

• confidence (float) – the confidence of the type prediction

• geometry (tuple[tuple[float, float], tuple[float, float]]) – 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 LayoutElement(layout_type, confidence, geometry)

Implements a layout region predicted by a layout detection model

Parameters:

• layout_type (str) – the predicted region class (e.g. ‘Title’, ‘Text’, ‘Table’, ‘Page-header’)

• confidence (float) – the confidence of the region prediction

• geometry (tuple[tuple[float, float], tuple[float, float]] | ndarray) – 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 Block(lines=[], artefacts=[], geometry=None, objectness_score=None)

Implements a block element as a collection of lines and artefacts

Parameters:

• lines (list[Line]) – list of line elements

• artefacts (list[Artefact]) – list of artefacts

• geometry (tuple[tuple[float, float], tuple[float, float]] | ndarray | None) – 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 Page(

page,

blocks,

page_idx,

dimensions,

orientation=None,

language=None,

layout=None,

tables=None,

)

Implements a page element as a collection of blocks

Parameters:

• page (ndarray) – image encoded as a numpy array in uint8

• blocks (list[Block]) – list of block elements

• page_idx (int) – the index of the page in the input raw document

• dimensions (tuple[int, int]) – the page size in pixels in format (height, width)

• orientation (dict[str, Any] | None) – a dictionary with the value of the rotation angle in degress and confidence of the prediction

• language (dict[str, Any] | None) – a dictionary with the language value and confidence of the prediction

• layout (list[LayoutElement]) – optional list of layout regions detected on the page

• tables (list[Table]) – optional list of tables recognized on the page. Words assigned to a table are removed from blocks.

show(interactive=True, preserve_aspect_ratio=False, **kwargs)

Overlay the result on a given image

Parameters:

• interactive (bool) – whether the display should be interactive

• preserve_aspect_ratio (bool) – 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='auto')

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

Parameters:

direction (str) – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’

Returns:

list of blocks & tables in reading order

Return type:

list[Block | Table]

export_as_markdown(direction='auto', escape=True, include_furniture=True)

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

Parameters:

• direction (str) – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’

• escape (bool) – whether the characters carrying a structural meaning in Markdown should be escaped

• include_furniture (bool) – whether page headers, page footers and footnotes should be included

Returns:

a Markdown string

Return type:

str

export_as_asciidoc(direction='auto', escape=True, include_furniture=True)

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

Parameters:

• direction (str) – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’

• escape (bool) – whether the characters and line markers carrying a structural meaning in AsciiDoc should be escaped

• include_furniture (bool) – whether page headers, page footers and footnotes should be included

Returns:

an AsciiDoc string

Return type:

str

export_as_html(direction='auto', include_furniture=True)

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

Parameters:

• direction (str) – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’

• include_furniture (bool) – whether page headers, page footers and footnotes should be included

Returns:

an HTML string

Return type:

str

export_as_xml(

file_title='docTR - XML export (hOCR)',

direction='auto',

reading_order=True,

)

Export the page as XML (hOCR-format), with its content sorted in reading order convention: kba/hocr-spec

Parameters:

• file_title (str) – the title of the XML file

• direction (str) – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’

• reading_order (bool) – whether the content should be linearized in reading order

Returns:

a tuple of the XML byte string, and its ElementTree

Return type:

tuple[bytes, ElementTree]

export(reading_order=True)

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

Parameters:

reading_order (bool) – 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

Return type:

dict[str, Any]

render(block_break='\n\n', direction='auto', include_furniture=True)

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

Parameters:

• block_break (str) – the string inserted between two blocks

• direction (str) – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’

• include_furniture (bool) – whether page headers, page footers and footnotes should be included

Returns:

the text of the page

Return type:

str

export_as(format, **kwargs)

Export the page in the requested format.

Parameters:

• format (str) – one of ‘markdown’/’md’, ‘asciidoc’/’adoc’, ‘html’, ‘text’/’txt’, ‘json’/’dict’, ‘xml’/’hocr’

• **kwargs (Any) – additional keyword arguments passed to the format-specific export method

Returns:

the exported page

Return type:

Any

KIEPage

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

class KIEPage(

page,

predictions,

page_idx,

dimensions,

orientation=None,

language=None,

layout=None,

)

Implements a KIE page element as a collection of predictions

Parameters:

• predictions (dict[str, list[Prediction]]) – Dictionary with list of block elements for each detection class

• page (ndarray) – image encoded as a numpy array in uint8

• page_idx (int) – the index of the page in the input raw document

• dimensions (tuple[int, int]) – the page size in pixels in format (height, width)

• orientation (dict[str, Any] | None) – a dictionary with the value of the rotation angle in degress and confidence of the prediction

• language (dict[str, Any] | None) – a dictionary with the language value and confidence of the prediction

• layout (list[LayoutElement]) – optional list of layout regions detected on the page

show(interactive=True, preserve_aspect_ratio=False, **kwargs)

Overlay the result on a given image

Parameters:

• interactive (bool) – whether the display should be interactive

• preserve_aspect_ratio (bool) – pass True if you passed True to the predictor

• **kwargs – keyword arguments passed to the matplotlib.pyplot.show method

export_as_markdown(direction='auto', escape=True)

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

Parameters:

• direction (str) – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’

• escape (bool) – whether the characters carrying a structural meaning in Markdown should be escaped

Returns:

a Markdown string with one section per detection class

Return type:

str

export_as_asciidoc(direction='auto', escape=True)

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

Parameters:

• direction (str) – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’

• escape (bool) – 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

Return type:

str

export_as_html(direction='auto')

Export the KIE page as semantic HTML, with the predictions of each class sorted in reading order

Return type:

str

export_as_xml(

file_title='docTR - XML export (hOCR)',

direction='auto',

reading_order=True,

)

Export the page as XML (hOCR-format), with the predictions of each class in reading order convention: kba/hocr-spec

Parameters:

• file_title (str) – the title of the XML file

• direction (str) – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’

• reading_order (bool) – whether the predictions of each class should be sorted in reading order

Returns:

a tuple of the XML byte string, and its ElementTree

Return type:

tuple[bytes, ElementTree]

export(reading_order=True)

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

Parameters:

reading_order (bool) – whether the predictions of each class should be sorted in reading order

Returns:

a JSON-serializable dict

Return type:

dict[str, Any]

render(prediction_break='\n\n', direction='auto')

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

Parameters:

• prediction_break (str) – the string inserted between two predictions

• direction (str) – 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

Return type:

str

export_as(format, **kwargs)

Export the KIE page in the requested format (‘markdown’/’md’, ‘asciidoc’/’adoc’, ‘html’, ‘text’/’txt’, ‘json’/’dict’, ‘xml’/’hocr’).

Return type:

Any

Document

A Document is a collection of Pages.

class Document(pages)

Implements a document element as a collection of pages

Parameters:

pages (list[Page]) – list of page elements

show(**kwargs)

Overlay the result on a given image

export_as_markdown(page_break='\n\n---\n\n', **kwargs)

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

Parameters:

• page_break (str) – the string inserted between two pages (a thematic break by default)

• **kwargs (Any) – additional keyword arguments passed to the Page.export_as_markdown method

Returns:

a Markdown string

Return type:

str

export_as_asciidoc(page_break='\n\n<<<\n\n', **kwargs)

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

Parameters:

• page_break (str) – the string inserted between two pages (an AsciiDoc page break by default)

• **kwargs (Any) – additional keyword arguments passed to the Page.export_as_asciidoc method

Returns:

an AsciiDoc string

Return type:

str

export_as_xml(**kwargs)

Export the document as XML (hOCR-format)

Parameters:

**kwargs (Any) – additional keyword arguments passed to the XML page export

Returns:

list of tuple of (bytes, ElementTree)

Return type:

list[tuple[bytes, ElementTree]]

export_as_html(page_break='<hr>', **kwargs)

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

Parameters:

• page_break (str) – the HTML snippet inserted between two pages

• **kwargs (Any) – additional keyword arguments passed to the page export

Returns:

an HTML string

Return type:

str

export(reading_order=True)

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

Parameters:

reading_order (bool) – whether the content of each page should be linearized in reading order

Returns:

a JSON-serializable dict

Return type:

dict[str, Any]

render(page_break='\n\n\n\n', **kwargs)

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

Parameters:

• page_break (str) – the string inserted between two pages

• **kwargs (Any) – additional keyword arguments passed to the Page.render / KIEPage.render method

Returns:

the text of the document

Return type:

str

export_as(format, **kwargs)

Export the document in the requested format (‘markdown’/’md’, ‘asciidoc’/’adoc’, ‘html’, ‘text’/’txt’, ‘json’/’dict’, ‘xml’/’hocr’).

Return type:

Any

KIEDocument

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

class KIEDocument(pages)

Implements a document element as a collection of pages

Parameters:

pages (list[KIEPage]) – list of page elements

show(**kwargs)

Overlay the result on a given image

File reading

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

read_pdf(file, scale=2, rgb_mode=True, password=None, **kwargs)

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 (str | Path | bytes) – the path to the PDF file

• scale (int) – rendering scale (1 corresponds to 72dpi)

• rgb_mode (bool) – if True, the output will be RGB, otherwise BGR

• password (str | None) – a password to unlock the document, if encrypted

• **kwargs (Any) – additional parameters to pypdfium2.PdfPage.render()

Returns:

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

Return type:

list[ndarray]

read_img_as_numpy(file, output_size=None, rgb_output=True)

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 (str | Path | bytes) – the path to the image file

• output_size (tuple[int, int] | None) – the expected output size of each page in format H x W

• rgb_output (bool) – 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

Return type:

ndarray

read_img_as_tensor(img_path, dtype=torch.float32)

Read an image file as a PyTorch tensor

Parameters:

• img_path (str | Path) – location of the image file

• dtype (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

Return type:

Tensor

decode_img_as_tensor(img_content, dtype=torch.float32)

Read a byte stream as a PyTorch tensor

Parameters:

• img_content (bytes) – bytes of a decoded image

• dtype (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

Return type:

Tensor

read_html(url, **kwargs)

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 (str) – URL of the target web page

• **kwargs (Any) – keyword arguments from weasyprint.HTML

Returns:

decoded PDF file as a bytes stream

Return type:

bytes

class DocumentFile

Read a document from multiple extensions

classmethod from_pdf(file, **kwargs)

Read a PDF file

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

Parameters:

• file (str | Path | bytes) – 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

Return type:

list[ndarray]

classmethod from_url(url, **kwargs)

Interpret a web page as a PDF document

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

Parameters:

• url (str) – 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

Return type:

list[ndarray]

classmethod from_images(files, **kwargs)

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 (Sequence[str | Path | bytes] | str | Path | bytes) – 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

Return type:

list[ndarray]

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 TextExporter

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, page_break=None, **kwargs)

Export a document page by page.

Parameters:

• document (Any) – the document to export

• page_break (str | None) – the string inserted between two pages (a format-specific default when None)

• **kwargs (Any) – additional keyword arguments passed to the page export

Returns:

the exported document as a string

Return type:

str

export_kie_page(page, direction='auto', escape=True)

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

Parameters:

• page (KIEPage) – the KIE page to export

• direction (str) – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’

• escape (bool) – 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

Return type:

str

export_page(

page,

direction='auto',

escape=True,

include_furniture=True,

block_break=None,

)

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

Parameters:

• page (Page) – the page to export

• direction (str) – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’

• escape (bool) – whether the characters or markers carrying a structural meaning should be neutralized

• include_furniture (bool) – whether page headers, page footers and footnotes should be included

• block_break (str | None) – the string inserted between two blocks (the format-specific default when None)

Returns:

the exported page as a string

Return type:

str

class MarkdownExporter

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, page_break=None, **kwargs)

Export a document page by page.

Parameters:

• document (Any) – the document to export

• page_break (str | None) – the string inserted between two pages (a format-specific default when None)

• **kwargs (Any) – additional keyword arguments passed to the page export

Returns:

the exported document as a string

Return type:

str

export_kie_page(page, direction='auto', escape=True)

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

Parameters:

• page (KIEPage) – the KIE page to export

• direction (str) – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’

• escape (bool) – 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

Return type:

str

export_page(

page,

direction='auto',

escape=True,

include_furniture=True,

block_break=None,

)

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

Parameters:

• page (Page) – the page to export

• direction (str) – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’

• escape (bool) – whether the characters or markers carrying a structural meaning should be neutralized

• include_furniture (bool) – whether page headers, page footers and footnotes should be included

• block_break (str | None) – the string inserted between two blocks (the format-specific default when None)

Returns:

the exported page as a string

Return type:

str

class AsciiDocExporter

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, page_break=None, **kwargs)

Export a document page by page.

Parameters:

• document (Any) – the document to export

• page_break (str | None) – the string inserted between two pages (a format-specific default when None)

• **kwargs (Any) – additional keyword arguments passed to the page export

Returns:

the exported document as a string

Return type:

str

export_kie_page(page, direction='auto', escape=True)

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

Parameters:

• page (KIEPage) – the KIE page to export

• direction (str) – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’

• escape (bool) – 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

Return type:

str

export_page(

page,

direction='auto',

escape=True,

include_furniture=True,

block_break=None,

)

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

Parameters:

• page (Page) – the page to export

• direction (str) – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’

• escape (bool) – whether the characters or markers carrying a structural meaning should be neutralized

• include_furniture (bool) – whether page headers, page footers and footnotes should be included

• block_break (str | None) – the string inserted between two blocks (the format-specific default when None)

Returns:

the exported page as a string

Return type:

str

class HTMLExporter

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_page(

page,

direction='auto',

escape=True,

include_furniture=True,

block_break=None,

)

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

Parameters:

• page (Page) – the page to export

• direction (str) – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’

• escape (bool) – whether the characters or markers carrying a structural meaning should be neutralized

• include_furniture (bool) – whether page headers, page footers and footnotes should be included

• block_break (str | None) – the string inserted between two blocks (the format-specific default when None)

Returns:

the exported page as a string

Return type:

str

export_kie_page(page, direction='auto', escape=True)

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

Parameters:

• page (KIEPage) – the KIE page to export

• direction (str) – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’

• escape (bool) – 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

Return type:

str

export_document(document, page_break=None, **kwargs)

Export a document page by page.

Parameters:

• document (Any) – the document to export

• page_break (str | None) – the string inserted between two pages (a format-specific default when None)

• **kwargs (Any) – additional keyword arguments passed to the page export

Returns:

the exported document as a string

Return type:

str

class XMLExporter

hOCR (XML) exporter for pages, KIE pages and documents. See the hOCR 1.2 specification for the XML convention: kba/hocr-spec

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

export_page(

page,

file_title='docTR - XML export (hOCR)',

direction='auto',

reading_order=True,

)

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

Parameters:

• page (Page) – the page to export

• file_title (str) – the title of the XML file

• direction (str) – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’

• reading_order (bool) – 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

Return type:

tuple[bytes, ElementTree]

export_kie_page(

page,

file_title='docTR - XML export (hOCR)',

direction='auto',

reading_order=True,

)

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

Parameters:

• page (KIEPage) – the KIE page to export

• file_title (str) – the title of the XML file

• direction (str) – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’

• reading_order (bool) – whether the predictions of each class should be sorted in reading order

Returns:

a tuple of the XML byte string, and its ElementTree

Return type:

tuple[bytes, ElementTree]

export_document(document, **kwargs)

Export a document as a list of hOCR pages.

Parameters:

• document (Any) – the document to export

• **kwargs (Any) – additional keyword arguments passed to the page export

Returns:

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

Return type:

list[tuple[bytes, ElementTree]]

page_reading_order(page, direction='auto')

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 (Page) – the page to linearize

• direction (str) – 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

Return type:

tuple[list[Any], list[str | None], str]

predictions_in_reading_order(page, predictions, direction='auto')

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

Parameters:

• page (KIEPage) – the KIE page the predictions belong to (used for its dimensions and detected language)

• predictions (list[Any]) – the predictions of one detection class

• direction (str) – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’

Returns:

the predictions, ordered logically

Return type:

list[Any]

to_json_safe(value)

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

Parameters:

value (Any) – any exported value

Returns:

the same value with every NumPy array converted to nested tuples and every NumPy scalar to its Python equivalent

Return type:

Any