# xavctn/img2table architecture

> Architecture diagram of the GitHub repository xavctn/img2table, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xavctn/img2table
- Repository: https://github.com/xavctn/img2table

## Overview

##### Project type and purpose
- This is a Python library (“img2table”) for detecting and extracting tables from images and PDF files using OpenCV‐based processing, with optional OCR integration. It is *not* a deployed application but rather a reusable package offering:
- Document ingestion (Image, PDF)
- Table detection (bordered & borderless pipelines)
- OCR abstraction layer to plug in various engines
- Data modeling of extracted tables
- Export to pandas DataFrame, HTML, or XLSX

##### Component relationships & data flow
1. **Input** (user script or notebook) feeds a source path/bytes →
2. **Document Ingestion**: `Image` or `PDF` class reads file, corrects rotation, produces one or multiple page images →
3. **Table Detection Pipeline**:
- Bordered detection sub‐pipeline runs edge/contour analysis to find tables →
- Borderless detection uses layout and whitespace analysis →
4. **OCR Processing** (optional): For each cell bbox, the chosen `OCRInstance` (strategy pattern) is invoked to extract text. If native PDF text available, skip OCR →
5. **Data Modeling**: Instantiate `TableCell`, `Row`, `Table` objects; collect them into `ExtractedTable`, compute metrics →
6. **Export**: Return a list/dict of `ExtractedTable` objects; user can call `.df`, `.html`, or `.to_xlsx()` to persist results.

##### Architectural patterns & principles
- Strategy Pattern for interchangeable OCR backends
- Pipeline / Chain of Responsibility for table processing (bordered → borderless → text)
- Factory‐like selection for Document type (Image vs PDF)
- Clear separation of concerns: ingestion, detection, OCR, modeling, export

##### Detail level
- Drill down each major pipeline into sub‐steps only if it clarifies flow (e.g., border detection → cell clustering → table creation).
- Config points (e.g., `min_confidence`, `implicit_rows`, `detect_rotation`).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Input
    Input["User Script/Notebook"]:::external

    %% Document Ingestion
    subgraph "Document Ingestion" 
        direction TB
        ImageLoader["Image Loader"]:::core
        PDFLoader["PDF Loader & Text Extractor"]:::core
    end

    %% Table Detection & Extraction
    subgraph "Table Detection Pipeline" 
        direction TB
        Bordered["BorderedTablePipeline"]:::core
        Borderless["BorderlessTablePipeline"]:::core
        CommonUtils["Common Processing Utilities"]:::core
        TextUtils["Text Processing Utilities"]:::core
    end

    %% OCR Abstraction Layer
    subgraph "OCR Abstraction Layer" 
        direction TB
        OCRBase["OCR Base Interface"]:::ocr
        subgraph "OCR Adapters"
            direction TB
            Tesseract["TesseractOCR"]:::ocr
            Paddle["PaddleOCR"]:::ocr
            Easy["EasyOCR"]:::ocr
            Surya["SuryaOCR"]:::ocr
            GoogleVision["GoogleVisionOCR"]:::ocr
            AWSTextract["AWS Textract OCR"]:::ocr
            Azure["AzureOCR"]:::ocr
            Doctr["DoctrOCR"]:::ocr
            PDFNative["PDF-native OCR"]:::ocr
        end
    end

    %% Data Models & Metrics
    subgraph "Data Models & Metrics"
        direction TB
        Cell["Cell Model"]:::model
        Row["Row Model"]:::model
        TableModel["Table Model"]:::model
        Line["Line Model"]:::model
        Extracted["ExtractedTable Wrapper"]:::model
        Metrics["Metrics Module"]:::model
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        OpenCV["OpenCV"]:::external
        Pandas["pandas"]:::external
        TextractAPI["AWS Textract API"]:::external
    end

    %% Flow
    Input -->|"provides path/bytes"| ImageLoader
    Input -->|"provides path/bytes"| PDFLoader
    ImageLoader -->|"pages images"| Bordered
    PDFLoader -->|"pages images or text"| Bordered
    Bordered --> CommonUtils
    Borderless --> CommonUtils
    CommonUtils --> TextUtils
    TextUtils --> CommonUtils
    CommonUtils -->|"raw cell bboxes"| OCRBase
    OCRBase --> Tesseract
    OCRBase --> Paddle
    OCRBase --> Easy
    OCRBase --> Surya
    OCRBase --> GoogleVision
    OCRBase --> AWSTextract
    OCRBase --> Azure
    OCRBase --> Doctr
    OCRBase --> PDFNative
    OCRBase -->|"text per cell"| Cell
    Cell --> Row
    Row --> TableModel
    TableModel --> Extracted
    Extracted --> Metrics
    Extracted -->|".df/.html/.to_xlsx()"| Pandas

    %% External usage
    Bordered --> OpenCV
    Borderless --> OpenCV

    %% Click Events
    click ImageLoader "https://github.com/xavctn/img2table/blob/main/src/img2table/document/image.py"
    click PDFLoader "https://github.com/xavctn/img2table/blob/main/src/img2table/document/pdf.py"
    click Bordered "https://github.com/xavctn/img2table/tree/main/src/img2table/tables/processing/bordered_tables/"
    click Borderless "https://github.com/xavctn/img2table/tree/main/src/img2table/tables/processing/borderless_tables/"
    click CommonUtils "https://github.com/xavctn/img2table/blob/main/src/img2table/tables/processing/common.py"
    click TextUtils "https://github.com/xavctn/img2table/tree/main/src/img2table/tables/processing/text/"
    click OCRBase "https://github.com/xavctn/img2table/blob/main/src/img2table/ocr/base.py"
    click Tesseract "https://github.com/xavctn/img2table/blob/main/src/img2table/ocr/tesseract.py"
    click Paddle "https://github.com/xavctn/img2table/blob/main/src/img2table/ocr/paddle.py"
    click Easy "https://github.com/xavctn/img2table/blob/main/src/img2table/ocr/easyocr.py"
    click Surya "https://github.com/xavctn/img2table/blob/main/src/img2table/ocr/surya.py"
    click GoogleVision "https://github.com/xavctn/img2table/blob/main/src/img2table/ocr/google_vision.py"
    click AWSTextract "https://github.com/xavctn/img2table/blob/main/src/img2table/ocr/aws_textract.py"
    click Azure "https://github.com/xavctn/img2table/blob/main/src/img2table/ocr/azure.py"
    click Doctr "https://github.com/xavctn/img2table/blob/main/src/img2table/ocr/doctr.py"
    click PDFNative "https://github.com/xavctn/img2table/blob/main/src/img2table/ocr/pdf.py"
    click Cell "https://github.com/xavctn/img2table/blob/main/src/img2table/tables/objects/cell.py"
    click Row "https://github.com/xavctn/img2table/blob/main/src/img2table/tables/objects/row.py"
    click TableModel "https://github.com/xavctn/img2table/blob/main/src/img2table/tables/objects/table.py"
    click Line "https://github.com/xavctn/img2table/blob/main/src/img2table/tables/objects/line.py"
    click Extracted "https://github.com/xavctn/img2table/blob/main/src/img2table/tables/objects/extraction.py"
    click Metrics "https://github.com/xavctn/img2table/blob/main/src/img2table/tables/metrics.py"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef ocr fill:#DFFFE0,stroke:#28A745,color:#28A745
    classDef model fill:#FFE8CC,stroke:#F66A0A,color:#F66A0A
    classDef external fill:#F0F0F0,stroke:#666666,color:#666666
```
