img2table

img2table is a Python library designed for identifying and extracting tables from heterogeneous documents, including native PDFs, scanned PDFs, and various image formats.

Key capabilities include:

• Plug-and-play extraction: Minimal configuration required for most documents.
• Complex structure handling: Supports tables with merged cells.
• OCR integration: Extracts table content by leveraging various OCR tools.
• Data formats: Returns extracted tables as simple objects, including a Pandas DataFrame representation.
• Excel export: Preserves original table structures when exporting to Excel.

Table detection in img2table uses two complementary paths to identify tables, depending on whether they have visible borders or rely on text layout:

1. Bordered Tables: Reconstructed from visible horizontal and vertical ruling lines. The algorithm detects lines, constructs a geometric grid of candidate cells, and clusters them into tables.
2. Borderless Tables: Reconstructed from repeated text alignment and persistent whitespace. The algorithm analyzes text layout, identifies vertical whitespace bands that persist across rows, and validates these sections against structural consistency rules.

The pipeline begins by creating a scale-aware foreground mask and computing document metrics (like typical character size and row spacing) to ensure detection works across different resolutions and scan qualities.

For tables with explicit ruling lines, the detection follows these steps:

• Graphical Line Detection: Uses smoothing, edge detection, and directional morphological filters (horizontal and vertical kernels) to isolate long, continuous lines while masking out text.
• Candidate Grid Construction: Finds pairs of horizontal lines to form row bands and uses vertical lines spanning those bands as column separators to create rectangular cells.
• Table Reconstruction: Clusters touching or aligned cells into tables. It can handle semi-bordered tables by inferring missing cells from surrounding lines or by using text baselines and vertical whitespace to supplement explicit borders.
• Validation: Removes rows or columns that contain no meaningful content to prevent line artifacts from being treated as table structure.

Install the core library using pip. The standard installation includes support for Tesseract OCR. Depending on your preferred OCR engine, you can install specific extras to enable support for other services like PaddleOCR, EasyOCR, or cloud-based providers like AWS and Google Vision.

# Standard installation (supports Tesseract)
pip install img2table

# Installation with specific OCR engines
pip install img2table[paddle]
pip install img2table[easyocr]
pip install img2table[doctr]
pip install img2table[surya]
pip install img2table[rapidocr]

# Installation with cloud OCR services
pip install img2table[gcp]
pip install img2table[aws]
pip install img2table[azure]

The project provides several Jupyter notebooks to demonstrate different use cases and advanced configurations:

• Basic usage: Demonstrates generic library usage with images, PDFs, and various OCR engines.
• Borderless tables: Focuses on specific techniques for extracting tables that lack visible borders.
• Implicit content: Demonstrates how to use the implicit_rows and implicit_columns parameters in the extract_tables method to handle tables with implicit structure.

# Refer to the following notebooks in the repository:
# - /examples/Basic_usage.ipynb
# - /examples/borderless.ipynb
# - /examples/Implicit.ipynb

An ExtractedTable is composed of the following components:

• bbox: A BBox object defining the table's location.
• title: An optional string representing the detected table title.
• content: An OrderedDict[int, list[TableCell]] where the key is the row index and the value is a list of TableCell objects representing that row.

A TableCell contains:

• bbox: A BBox object for the specific cell.
• value: The string content of the cell (can be None).

When using img2table, keep the following limitations and requirements in mind:

• OCR Dependency: Table extraction quality is highly dependent on the quality of the OCR used. Tables without detectable OCR data will not be returned by the library.
• Document Background: The library is optimized for documents with white or light backgrounds. Effectiveness on dark or complex backgrounds is not guaranteed.
• Detection Algorithms: Table detection using only OpenCV processing has limitations. If tables are not being detected, consider using CNN or LLM-based solutions.
• Algorithm Details: For a technical deep dive into how bordered and borderless table detection works, refer to the table detection algorithms documentation.

Authentication can be handled via the GOOGLE_APPLICATION_CREDENTIALS environment variable. Alternatively, provide an api_key directly.

Parameters:

• api_key: Google Vision API key.
• timeout: API request timeout in seconds.

from img2table.ocr import VisionOCR

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

PaddleOCR is a deep learning-based OCR. Relevant models are downloaded on first use.

Parameters:

• lang: Language for extraction (e.g., "en").
• kw: A dictionary of additional keyword arguments passed to the PaddleOCR constructor.

from img2table.ocr import PaddleOCR

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

Uses the AWS Textract DetectDocumentText API. Authentication can be done via boto3 credentials (environment variables/config files) or by passing credentials directly to the constructor.

Parameters:

• aws_access_key_id: AWS access key ID.
• aws_secret_access_key: AWS secret access key.
• aws_session_token: AWS temporary session token.
• region: AWS server region.

from img2table.ocr import TextractOCR

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