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)[source]#

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

  • size (the page's)

  • 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

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)[source]#

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)[source]#

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.

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)[source]#

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)[source]#

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

show(interactive=True, preserve_aspect_ratio=False, **kwargs)[source]#

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

Document#

A Document is a collection of Pages.

class Document(pages)[source]#

Implements a document element as a collection of pages

Parameters:

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

show(**kwargs)[source]#

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)[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 (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)[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 (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)[source]#

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)[source]#

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)[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 (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[source]#

Read a document from multiple extensions

classmethod from_pdf(file, **kwargs)[source]#

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)[source]#

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)[source]#

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]