img2table

img2table is a simple, easy to use, table identification and extraction Python Library based on OpenCV image processing that supports most common image file formats as well as PDF files.

Thanks to its design, it provides a practical and lighter alternative to Neural Networks based solutions, especially for usage on CPU.

Table of contents

• Installation
• Features
• Usage
  • Documents
    • Images
    • PDF
  • Supported OCRs
  • Table extraction
  • Excel export
• Examples
• FYI / Caveats

Installation

The library can be installed via pip:

Features

• Plug-and-play table extraction from heterogeneous documents, including native PDFs, scanned PDFs and images, with minimal configuration
• Handling of complex table structures such as merged cells
• Table content extraction by providing support for OCR services / tools
• Extracted tables are returned as a simple object, including a Pandas DataFrame representation
• Export extracted tables to an Excel file, preserving their original structure

Usage

Documents

Images

Images are instantiated as follows :

from img2table.document import Image

image = Image(src,
              detect_rotation=False)

Parameters

src : str, pathlib.Path, bytes or io.BytesIO, required Image source detect_rotation : bool, optional, default False Detect and correct skew/rotation of the image
The implemented method to handle skewed/rotated images supports skew angles up to 45° and is based on the publication by Huang, 2020.
Setting the detect_rotation parameter to True, image coordinates and bounding boxes returned by other methods might not correspond to the original image.

PDF

PDF files are instantiated as follows :

from img2table.document import PDF

pdf = PDF(src,
          pages=[0, 2],
          detect_rotation=False,
          pdf_text_extraction=True)

Parameters

src : str, pathlib.Path, bytes or io.BytesIO, required PDF source pages : list, optional, default None List of PDF page indexes to be processed. If None, all pages are processed detect_rotation : bool, optional, default False Detect and correct skew/rotation of extracted images from the PDF pdf_text_extraction : bool, optional, default True Extract text from the PDF file for native PDFs

PDF pages are converted to images with a 200 DPI for table identification.

OCR

img2table provides an interface for several OCR services and tools in order to parse table content.
If possible (i.e for native PDF), PDF text will be extracted directly from the file and the OCR service/tool will not be called.

from img2table.ocr import TesseractOCR

ocr = TesseractOCR(n_threads=1,
                   lang="eng",
                   psm=11,
                   tessdata_dir="...")

from img2table.ocr import PaddleOCR

ocr = PaddleOCR(lang="en",
                kw={"kwarg": kw_value, ...})

from img2table.ocr import EasyOCR

ocr = EasyOCR(lang=["en"],
              kw={"kwarg": kw_value, ...})

from img2table.ocr import DocTR

ocr = DocTR(detect_language=False,
            kw={"kwarg": kw_value, ...})

from img2table.ocr import RapidOCR

ocr = RapidOCR(params={"Rec.lang_type": ..., "kwarg": kw_value, ...})

from img2table.ocr import SuryaOCR

ocr = SuryaOCR(langs=["en"])

from img2table.ocr import VisionOCR

ocr = VisionOCR(api_key="api_key", timeout=15)

from img2table.ocr import TextractOCR

ocr = TextractOCR(aws_access_key_id="***",
                  aws_secret_access_key="***",
                  aws_session_token="***",
                  region="eu-west-1")

from img2table.ocr import AzureOCR

ocr = AzureOCR(endpoint="abc.azure.com",
               subscription_key="***")

Table extraction

Multiple tables can be extracted at once from a PDF page/ an image using the extract_tables method of a document.

from img2table.ocr import TesseractOCR
from img2table.document import Image

# Instantiation of OCR
ocr = TesseractOCR()

# Instantiation of document, either an image or a PDF
doc = Image(src)

# Table extraction
extracted_tables = doc.extract_tables(ocr=ocr,
                                      implicit_rows=False,
                                      implicit_columns=False,
                                      borderless_tables=False,
                                      min_confidence=50,
                                      max_workers=1)

Parameters

ocr : OCRInstance, optional, default None OCR instance used to parse document text. If None, cells content will not be extracted implicit_rows : bool, optional, default False Boolean indicating if implicit rows should be identified - check related example implicit_columns : bool, optional, default False Boolean indicating if implicit columns should be identified - check related example borderless_tables : bool, optional, default False Boolean indicating if borderless tables are extracted on top of bordered tables. min_confidence : int, optional, default 50 Minimum confidence level from OCR in order to process text, from 0 (worst) to 99 (best) max_workers : int, optional, default 1 Number of concurrent workers used for table extraction. Mainly useful for multi-page PDFs.

Method return

The ExtractedTable class is used to model extracted tables from documents.

Attributes

bbox : BBox Table bounding box, with absolute coordinates and normalized coordinates available via bbox.relative title : str Extracted title of the table content : OrderedDict Dict with row indexes as keys and list of TableCell objects as values df : pd.DataFrame Pandas DataFrame representation of the table html : str HTML representation of the table

In order to access bounding boxes at the cell level, you can use the following code snippet :

for id_row, row in enumerate(table.content.values()):
    for id_col, cell in enumerate(row):
        x1 = cell.bbox.x1
        y1 = cell.bbox.y1
        x2 = cell.bbox.x2
        y2 = cell.bbox.y2
        value = cell.value

Normalized coordinates (in percentage of image height / width) are also available on the same object:

relative_bbox = cell.bbox.relative
x1 = relative_bbox.x1
y1 = relative_bbox.y1
x2 = relative_bbox.x2
y2 = relative_bbox.y2

Images

extract_tables method from the Image class returns a list of ExtractedTable objects.

output = [ExtractedTable(...), ExtractedTable(...), ...]

PDF

extract_tables method from the PDF class returns an OrderedDict object with page indexes as keys and lists of ExtractedTable objects.

output = {
    0: [ExtractedTable(...), ...],
    1: [],
    ...
    last_page: [ExtractedTable(...), ...]
}

Excel export

Tables extracted from a document can be exported to a xlsx file. The resulting file is composed of one worksheet per extracted table.
Method arguments are mostly common with the extract_tables method.

from img2table.ocr import TesseractOCR
from img2table.document import Image

# Instantiation of OCR
ocr = TesseractOCR()

# Instantiation of document, either an image or a PDF
doc = Image(src)

# Extraction of tables and creation of a xlsx file containing tables
doc.to_xlsx(dest=dest,
            ocr=ocr,
            implicit_rows=False,
            implicit_columns=False,
            borderless_tables=False,
            min_confidence=50,
            max_workers=1)

Parameters

dest : str, pathlib.Path or io.BytesIO, required Destination for xlsx file ocr : OCRInstance, optional, default None OCR instance used to parse document text. If None, cells content will not be extracted implicit_rows : bool, optional, default False Boolean indicating if implicit rows should be identified - check related example implicit_columns : bool, optional, default False Boolean indicating if implicit columns should be identified - check related example borderless_tables : bool, optional, default False Boolean indicating if borderless tables are extracted. min_confidence : int, optional, default 50 Minimum confidence level from OCR in order to process text, from 0 (worst) to 99 (best) max_workers : int, optional, default 1 Number of concurrent workers used for table extraction. Mainly useful for multi-page PDFs.

Returns

If a io.BytesIO buffer is passed as dest arg, it is returned containing xlsx data

Examples

Several Jupyter notebooks with examples are available :

• Basic usage: generic library usage, including examples with images, PDF and OCRs
• Borderless tables: specific examples dedicated to the extraction of borderless tables
• Implicit content: illustrated effect of the parameter implicit_rows/implicit_columns of the extract_tables method

FYI / Caveats

• For a high-level description of the implemented bordered and borderless table detection algorithms, see the table detection algorithms documentation.
• For table extraction, results are highly dependent on OCR quality. By design, tables where no OCR data can be found are not returned.
• The library is tailored for usage on documents with white/light background. Effectiveness can not be guaranteed on other type of documents.
• Table detection using only OpenCV processing can have some limitations. If the library fails to detect tables, you may check CNN / LLM based solutions.