TableCV

TableCV turns OCR text boxes into a pandas.DataFrame. Use it when you already have OCR output from an image and want a simple table-like result without writing row and column grouping logic yourself.

OCR means optical character recognition: software reads text from an image. Most OCR tools return each piece of text with a bounding box, which is the rectangle around that text. TableCV uses those rectangles to estimate which text belongs in each row and column.

Why Use It

• Works with any OCR tool that can return text boxes.
• Returns a familiar pandas.DataFrame.
• Keeps the core table extraction separate from heavy OCR engines.
• Supports an optional PaddleOCR path for users who want OCR and table extraction in one call.

Installation

For table extraction from OCR results:

pip install tablecv

For the optional PaddleOCR helper:

pip install "tablecv[paddle]"

On Linux, PaddlePaddle may also need the system OpenMP runtime. For Ubuntu or Debian-based systems, install libgomp1 if importing Paddle fails with a libgomp.so.1 error.

Requirements

• Python 3.13+
• pandas and shapely for the core extraction path
• PaddleOCR only if you call extract_table()

Quick Start With Existing OCR Results

Use extract_table_from_ocr() when your OCR tool has already read the image.

from tablecv import extract_table_from_ocr

ocr_results = [
    ((0, 0, 10, 5), "Name"),
    ((20, 0, 10, 5), "Qty"),
    ((0, 20, 10, 5), "Tea"),
    ((20, 20, 10, 5), "2"),
    ((0, 40, 10, 5), "Coffee"),
    ((20, 40, 10, 5), "1"),
]

df = extract_table_from_ocr(ocr_results)
print(df)

The OCR result format is:

((x, y, width, height), text)

Here, x and y are the top-left position of the text box. width and height are the size of that box.

Quick Start With PaddleOCR

Install the optional extra first:

pip install "tablecv[paddle]"

Then call extract_table() with an image path:

from tablecv import extract_table

df = extract_table("invoice.png")
print(df)

extract_table() initializes PaddleOCR lazily. Importing tablecv does not download OCR models or require PaddleOCR unless you call this function.

How It Works

TableCV estimates a table in three broad steps:

1. It finds the overall table area from all OCR boxes.
2. It groups boxes that share similar vertical positions into rows.
3. It uses the most common row width as the reference for column positions.

This works best for documents where text boxes line up in clear rows and columns.

Limitations

TableCV is a lightweight table estimator, not a full document understanding system.

• It does not detect table borders or merged cells.
• It expects OCR boxes to be close to reading order.
• Skewed, rotated, handwritten, or heavily nested tables may need preprocessing.
• Real OCR accuracy depends on the OCR engine, image quality, language, and font.

Troubleshooting

libgomp.so.1 Missing

PaddlePaddle depends on an OpenMP runtime on Linux. If extract_table() fails while importing Paddle with libgomp.so.1: cannot open shared object file, install the system package:

sudo apt-get update
sudo apt-get install libgomp1

You do not need PaddleOCR or libgomp1 for extract_table_from_ocr().

Development

This project uses uv, Ruff, pytest, Bandit, and PyPI Trusted Publishing.

make sync
make test
make coverage
make check-commit
make build

Default tests use synthetic OCR boxes and do not download OCR models. Tests that require PaddleOCR, image files, model downloads, or external binaries should be marked as integration.

Publishing

Pushes to main run the package quality gate and publish to PyPI with Trusted Publishing. Before this works, configure PyPI to trust:

• owner: inquilabee
• repository: TableCV
• workflow: .github/workflows/python-publish.yml
• environment: pypi