gmft

give

formatted

tables!

There are many pdfs out there, and many of those pdfs have tables. But despite a plethora of table extraction options, there is still no definitive extraction method.

About

gmft is a toolkit for converting pdf tables to many formats. It is lightweight, modular, and performant.

Batteries included: it just works, offering strong performance with the default settings.

It relies on microsoft's Table Transformers, qualitatively the most performant and reliable of the many alternatives.

Install: pip install gmft

Quickstarts: demo notebook, bulk extract, readthedocs.

Documentation: readthedocs

Why use gmft?

Fast, lightweight, and performant, gmft is a great choice for extracting tables from pdfs.

The extraction quality is superb: check out the bulk extract notebook for approximate quality. When testing the same tables across many table extraction options, gmft fares extremely well, with arguably the best extraction quality.

Many Formats

gmft supports the following export options:

Pandas dataframe (!)
By extension: markdown, latex, html, csv, json, etc.
List of text + positions
Cropped image of table
Table caption

Cropped images are useful for directly feeding into a vision recognizer, like:

GPT-4 vision
Mathpix/Adobe/Google/Amazon/Azure/etc.

Cropped images are also excellent for verifying correctness of output.

Lightweight

No GPU necessary

Because of the few dependencies, gmft is very lightweight. The architecture (Table Transformer) allows gmft to run on cpu.

High throughput

Benchmark using Colab's cpu indicates an approximate rate of ~1.381 s/page; converting to df takes ~1.168 s/table. See the comparison here. This makes gmft about 10x faster than alternatives like unstructured, nougat, and open-parse/unitable on cpu. Here's how:

The base model, Smock et al.'s Table Transformer, is blazing fast.
gmft focuses on table extraction, so figures, titles, sections, etc. are not extracted.
In most cases, OCR is not necessary; pdfs already contain text positional data. Using this existing data drastically speeds up inference. With that being said, gmft can still extract tables from images and scanned pdfs through the image output.
PyPDFium2 is chosen for its high throughput and permissive license.

Few dependencies

Many pdf extractors require detectron2, poppler, paddleocr, tesseract etc., which may require external installation. Detectron2 is particularly difficult to install on windows. OCR models may require tesseract or paddleocr.

gmft can be installed in one line: pip install gmft. But it may help to have transformers and pytorch preinstalled.

gmft mostly relies on pypdfium2 and transformers. On the first run, gmft downloads Microsoft's TATR from huggingface, which requires ~270mB total and is saved to ~/.cache/huggingface/hub/models--microsoft--table-{transformer-detection, structure-recognition} and ~/.cache/huggingface/hub/models--timm--resnet18.a1_in1k.

Reliable

gmft uses Microsoft's Table Transformer (TATR), which is trained on a diverse dataset PubTables-1M. Many alternative methods were considered, and TATR was ultimately chosen for several reasons, among them high reliability.

The authors are confident that the extraction quality is unmatched. When the model fails, it is usually an OCR issue, merged cell, or false positive. Even in these cases, the text is still highly useable. Alignment of a value to its row/column header tends to be very accurate because of the underlying procedural algorithm.

We invite you to explore the comparison notebooks to survey use cases and compare results.

Modular

By subclassing the BasePDFDocument and BasePage classes, gmft's design supports other PDF extraction methods (like PyMuPDF, PyPDF, pdfplumber etc.).

By subclassing TableDetector and TableFormatter, different architectures and alternative table detection/structure extraction methods are possible. Fine-tuned models may be specified by path to huggingface hub.

Configurable

See the config guide for discussion on gmft settings.

Quickstart

See the docs and the config guide for more information. The demo notebook and bulk extract contain more comprehensive code examples.

from gmft import CroppedTable, TableDetector, AutoTableFormatter
from gmft.pdf_bindings import PyPDFium2Document

detector = TableDetector()
formatter = AutoTableFormatter()

def ingest_pdf(pdf_path): # produces list[CroppedTable]
    doc = PyPDFium2Document(pdf_path)
    tables = []
    for page in doc:
        tables += detector.extract(page)
    return tables, doc

tables, doc = ingest_pdf("path/to/pdf.pdf")
doc.close() # once you're done with the document

Discussion

New features

[Experimental] Multi-indices (multiple column headers) are now supported in v0.2 with TATRFormatConfig.enable_multi_header = True.

[Experimental] Spanning cells are now supported in v0.2 with TATRFormatConfig.semantic_spanning_cells = True.

Rotated tables are now supported in v0.0.4.

Limitations

False detection of references, indexes, and large columnar text.

Slightly askew tables.

Acknowledgements

A tremendous thank you to the PubTables1M (and Table Transformer) authors: Brandon Smock, Rohith Pesala, and Robin Abraham, for making gmft possible. The image->csv step is based on from TATR's inference.py code, but it has been rewritten with some adjustments for ease of use.

Thank you to Niels Rogge for porting TATR to huggingface and writing the visualization code.

Alternatives

See comparison.

Gmft focuses highly on pdf tables. For tables, another great option is img2table, which is non-deep and attains great results.

Nougat is excellent for both pdf table extraction and document understanding. It outputs full mathpix markdown (.mmd), which includes latex formulas, bold/italics, and fully latex-typeset tables. However, a gpu is highly recommended.

For general document understanding, I recommend checking out open-parse, unstructured, surya, deepdoctection, and DocTR. Open-parse and unstructured do quite well on the same example pdfs in terms of extraction quality.

Open-parse allows extraction of auxiliary information like headers, paragraphs, etc., useful for RAG. In addition to the Table Transformer, open-parse also offers UniTable, a newer model which achieves SOTA results in many datasets like PubLayNet and FinTabNet. Though UniTable support in gmft is slated for the future, UniTable is much larger (~1.5 GB) and runs much slower (almost x90 longer!) on cpu. Therefore, TATR is still preferred for its speed. In addition, contrary to the table transformer, Unitable may fail first through misalignment because of misplaced html tags. This may impact use cases where alignment is critical.

License

gmft is released under MIT.

PyMuPDF support is available in a separate repository in observance of pymupdf's AGPL 3.0 license.

bravet/gmft