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

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', include_figures: bool = False) → list[Block | Table | LayoutElement]¶

Return the content of the page (blocks, tables and optionally figures) sorted in reading order.

Parameters:

direction – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’
include_figures – whether to return the figure regions too

Returns:

list of blocks, tables and, if requested, figures in reading order

export_as_markdown(direction: str = 'auto', escape: bool = True, include_furniture: bool = True, images: str | FigureEncoder | None = 'placeholder') → 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
images – how to render the figures: ‘none’, ‘placeholder’, ‘embedded’, or a FigureEncoder (required for ‘referenced’)

Returns:

a Markdown string

export_as_asciidoc(direction: str = 'auto', escape: bool = True, include_furniture: bool = True, images: str | FigureEncoder | None = 'placeholder') → 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
images – how to render the figures: ‘none’, ‘placeholder’, ‘embedded’, or a FigureEncoder (required for ‘referenced’)

Returns:

an AsciiDoc string

export_as_html(direction: str = 'auto', include_furniture: bool = True, images: str | FigureEncoder | None = 'placeholder') → 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
images – how to render the figures: ‘none’, ‘placeholder’, ‘embedded’, or a FigureEncoder (required for ‘referenced’)

Returns:

an HTML string

export_as_xml(file_title: str = 'docTR - XML export (hOCR)', direction: str = 'auto', reading_order: bool = True, dpi: int = 72) → 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
dpi – the page resolution in dots per inch, used to estimate font sizes (x_size, x_fsize)

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, dpi: int = 72) → 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
dpi – the page resolution in dots per inch, used to estimate font sizes (x_size, x_fsize)

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 (e.g. images, not supported by KIE pages)

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 (e.g. images, not supported by KIE pages)

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 (e.g. images, not supported by KIE pages)

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, images: str | FigureEncoder | None = 'placeholder') → 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)
images – how to render the figures: ‘none’, ‘placeholder’, ‘embedded’, or a FigureEncoder (required for ‘referenced’)

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 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)
images – how to render the figures: ‘none’, ‘placeholder’, ‘embedded’, or a FigureEncoder (required for ‘referenced’)

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 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)
images – how to render the figures: ‘none’, ‘placeholder’, ‘embedded’, or a FigureEncoder (required for ‘referenced’)

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 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)
images – how to render the figures: ‘none’, ‘placeholder’, ‘embedded’, or a FigureEncoder (required for ‘referenced’)

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, dpi: int = 72) → 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
dpi – the page resolution in dots per inch, used to estimate font sizes (x_size, x_fsize)

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, dpi: int = 72) → tuple[bytes, ElementTree][source]¶

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

Figures are exported as ocr_photo areas.

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.
dpi – the page resolution in dots per inch, used to estimate font sizes (x_size, x_fsize)

Returns:

a tuple of the XML byte string, and its ElementTree

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

Linearize the content of a page (blocks, tables and optionally figures) in reading order

The result is cached on the page, so a page exported to several formats is ordered once. The figures always take part in the ordering, include_figures only controls whether they are returned.

Parameters:

page – the page to linearize
direction – reading direction, one of ‘auto’, ‘ltr’, ‘rtl’, ‘ttb-rtl’ or ‘ttb-ltr’
include_figures – whether to return the figure regions too

Returns:

the ordered items, 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

Figures¶

When the predictor runs the layout model (detect_layout=True or detect_tables=True), the detected figures take part in the reading order, and the Markdown, AsciiDoc and HTML exports render them according to their images argument, an image mode or a configured FigureEncoder:

'placeholder' (default): a comment marks each figure ( in Markdown and HTML, // image in AsciiDoc)
'none': the figures are left out
'embedded': each figure is cropped and inlined as a base64 data URI
'referenced': each crop is written to an image directory and linked by its relative path, which needs a configured encoder: images=FigureEncoder("referenced", image_dir=...). Set path_prefix when the export is not written to the working directory: it locates the image directory from the export. The file names carry the position and a hash of the figure (e.g. page1_figure2-3fa2b1c9.png), so several documents can share a directory.

Note

Once a figure carries its pixels ('embedded' and 'referenced'), the text recognized inside it is left out of the export, since the image shows it, and its caption becomes the alternative text of the image. A figure which cannot be cropped (e.g. on a page restored from a JSON export) falls back to a placeholder and keeps its text. page.items_in_reading_order(include_figures=True) returns the figures along with the blocks and tables.

from doctr.io import DocumentFile, FigureEncoder
from doctr.models import ocr_predictor

predictor = ocr_predictor(pretrained=True, detect_layout=True)
doc = predictor(DocumentFile.from_pdf("report.pdf"))

# A self-contained Markdown file
markdown = doc.export_as_markdown(images="embedded")
# ... or one that links to the crops written to `assets`
markdown = doc.export_as_markdown(images=FigureEncoder("referenced", image_dir="assets"))

The caption also stays visible: an italic paragraph under the image in Markdown, a <figcaption> in HTML and a block title in AsciiDoc. Plain text never carries figures, and hOCR positions them as ocr_photo areas. A figure lying (at least half) in a page header or footer, e.g. a logo, is read with that furniture, and left out with it by include_furniture=False.

The command line exposes the same options: --images picks the mode, --image_format the file format, and in referenced mode the crops are written to --image_dir (by default <output name>_images next to the output):

doctr-cli --input_path report.pdf --detect_layout --output report.md --images referenced

class doctr.io.FigureEncoder(mode: str = 'placeholder', image_dir: str | Path | None = None, path_prefix: str | PathLike[str] | None = None, image_format: str = 'png', quality: int = 95, padding: float = 0.0)[source]¶

Render the figures detected by the layout model in the Markdown, AsciiDoc and HTML exports

none: no figures
placeholder: a comment marks each figure
embedded: each crop is inlined as a base64 data URI
referenced: each crop is written to image_dir and linked by its relative path

With their pixels (‘embedded’ or ‘referenced’), the text recognized inside the figures is left out of the export. Written files are named after the figure position and content, e.g. page1_figure2-3fa2b1c9.png.

>>> from doctr.io import FigureEncoder
>>> markdown = page.export_as_markdown(images=FigureEncoder("referenced", image_dir="assets"))

Parameters:

mode – one of ‘none’, ‘placeholder’, ‘embedded’ or ‘referenced’
image_dir – directory the crops are written to (required in ‘referenced’ mode)
path_prefix – location of image_dir relative to the export (image_dir by default)
image_format – one of ‘png’, ‘jpg’, ‘jpeg’ or ‘webp’
quality – quality of the lossy formats, between 0 and 100
padding – relative margin added around each region

property enabled: bool¶: Whether the figures appear in the export

property materializes: bool¶: Whether the figures are exported with their pixels

classmethod resolve(images: str | FigureEncoder | None) → FigureEncoder[source]¶

Build an encoder from the images argument of an export method

Parameters:: images – an image mode, an encoder, or None (same as ‘none’)
Returns:: the encoder

source(page: Page, region: LayoutElement, index: int) → str | None[source]¶

Return the image source of a figure, encoded (and written) on first use

Parameters:

page – the page of the figure
region – the figure region
index – 1-based index of the figure on the page, used in the file name

Returns:

a data URI or a relative path, None without pixels

doctr.io.crop_layout_region(page_img: ndarray | None, geometry: Any, padding: float = 0.0) → ndarray | None[source]¶

Crop a layout region out of its page image, de-rotating rotated regions

Parameters:

page_img – the page image, None or empty when the page has no pixels
geometry – the relative geometry of the region, a straight box or a (4, 2) polygon
padding – relative margin added on each side

Returns:

the crop, or None without pixels or for a region smaller than 2x2 pixels

doctr.io.encode_crop(crop: ndarray, image_format: str = 'png', quality: int = 95) → bytes[source]¶

Encode an RGB(A) crop into an image file format

Parameters:

crop – the crop to encode
image_format – one of ‘png’, ‘jpg’, ‘jpeg’ or ‘webp’
quality – quality of the lossy formats, between 0 and 100

Returns:

the encoded image

doctr.io.picture_regions(page: Page) → list[LayoutElement][source]¶

Return the figure regions of a page, without those nested in a larger figure

Parameters:: page – the page
Returns:: the figure regions, in detection order

doctr.io.is_picture_region(region: LayoutElement) → bool[source]¶

Check whether a layout region is a figure

Parameters:: region – the layout region
Returns:: True for a figure region

doctr.io.is_picture_label(label: str | None) → bool[source]¶

Check whether a layout label denotes a figure, i.e. a float that is not a table (e.g. ‘Picture’, ‘Chart’)

Parameters:: label – the layout label
Returns:: True for a figure label