sheet-me 📄➡️📊

sheet-me is a Python tool that takes scanned or crooked PDF documents (like scanned tables or printed lists) and automatically extracts them into clean, beautifully formatted Excel spreadsheets.

It handles the hard parts of OCR (Optical Character Recognition) for you, such as straightening tilted pages (deskewing) and aligning text columns into rows.

---

How It Works (At a Glance)

1. Straightening (Deskewing): It detects if a page is tilted and rotates it to make it straight.
2. Reading (OCR): It extracts the text and coordinates of all words on the page.
3. Aligning (Table Parsing): It groups words that are on the same line into rows and classifies them into columns.
4. Exporting (Excel Generator): It creates a professionally designed Excel file with automatic column widths, aligned text, and zebra-striped rows.

---

🚀 Step-by-Step Guide for Beginners

If you are new to Python, follow these steps to get sheet-me running on your computer.

Step 1: Set Up Python Virtual Environment

It is best practice to run Python projects inside a virtual environment to keep things clean. Open your terminal in the project folder and run:

# Create a virtual environment named 'venv'
python3 -m venv venv

# Activate the virtual environment
source venv/bin/activate

Step 2: Install sheet-me

Install the package along with its dependencies by running:

pip install -e .

Step 3: Run the sheet-me Command-Line Tool

You can use sheet-me directly from the terminal without writing any code.

Option A: Quick Run (Automatic Generic Table Layout)

To run the extractor on any PDF table out-of-the-box:

sheet-me --pdf path/to/my_document.pdf

This automatically groups cells into rows sequentially from left to right and exports them to a styled Excel sheet named my_document_extracted.xlsx.

Option B: AI Agent-Guided Run (Recommended for Assisted Development)

If you are developing inside an editor equipped with an agentic AI coding assistant (such as Antigravity), you can prompt the assistant to perform the coordinate calculations and run the pipeline autonomously:

"Prompt: Antigravity, analyze the column geometries on sample_document.pdf, write a custom configuration layout, and run the sheet-me CLI tool to generate the spreadsheet." The agent will automatically inspect the document structure, extract column positions, adjust y-limits, and generate a customized spreadsheet.

Option C: Manual Configuration-Driven Run

For complex tables where columns need specific manual boundaries, headers, or text cleaning:

1. Create a configuration file named sample_config.json (see the example format below).
2. Run the tool:

sheet-me --pdf sample_document.pdf --config sample_config.json

---

🛠️ Configuration File Format (sample_config.json)

To customize column boundaries, cleaning rules, and header details, create a JSON file with this structure:

{
  "title": "MY CUSTOM REPORT TITLE",
  "resolution": 150,
  "overlap_threshold": 0.25,
  "max_box_height": 35,
  "exclude_keywords": ["Principal", "Page Total"],
  "header_y_limit": 100,
  "columns": [
    {
      "name": "id",
      "x_range": [0, 150],
      "cleaner": "integer"
    },
    {
      "name": "name",
      "x_range": [150, 500],
      "cleaner": "name"
    }
  ],
  "headers": ["ID", "Full Name"],
  "alignments": {
    "id": "center",
    "name": "left"
  }
}

Supported Column Cleaners:

• "integer": Fixes letters read as digits (e.g. o/O to 0) and keeps only numbers.
• "name": Standardizes capitalization and strips special characters.
• "ht_no": Cleans Hall Ticket numbers or code identifiers.

---

🐍 Customizing via Python Code (Advanced)

import os
from sheet_me import OCREngine, DeskewManager, TableParser, ExcelGenerator

# 1. Setup paths
pdf_path = "my_scanned_document.pdf"
output_xlsx = "output_report.xlsx"

# 2. Extract raw text boxes from the PDF (straightens pages automatically)
ocr_engine = OCREngine(gpu=True)
deskew_manager = DeskewManager()

print("Processing PDF...")
pages_data = ocr_engine.extract_pdf_pages_ocr(
    pdf_path=pdf_path,
    resolution=150,
    deskew_manager=deskew_manager
)

# 3. Define your columns
# Estimate column boundaries in horizontal pixels (from 0 to page width)
columns_definition = [
    {
        "name": "id",
        "x_range": (0, 150),
        "cleaner": TableParser.clean_integer  # Removes non-numbers
    },
    {
        "name": "full_name",
        "x_range": (150, 500),
        "cleaner": TableParser.clean_name     # Standardizes capitalization
    },
    {
        "name": "identifier",
        "x_range": (500, 800),
        "cleaner": TableParser.clean_alphanumeric
    }
]

# 4. Parse the extracted data into rows
parser = TableParser()
all_rows = []

for page in pages_data:
    boxes = [parser.compute_box_geometry(b) for b in page['boxes']]
    
    # Filter out page headers or vertical line gridlines
    filtered_boxes = [b for b in boxes if b['height'] <= 35]
    
    # Group boxes into horizontal rows
    rows = parser.group_boxes_into_rows(filtered_boxes, overlap_threshold=0.25)
    
    for row_boxes in rows:
        parsed_row = parser.classify_columns(row_boxes, columns_definition)
        
        # Keep row if it has at least a name
        if parsed_row['full_name']:
            all_rows.append(parsed_row)

# 5. Save the final beautiful Excel file
ExcelGenerator.save_to_file(
    data=all_rows,
    headers=["ID", "Full Name", "Identifier"],
    column_keys=["id", "full_name", "identifier"],
    output_path=output_xlsx,
    title="EXTRACTED OCR DATABASE REPORT",
    column_alignments={
        "id": "center",
        "full_name": "left",
        "identifier": "center"
    }
)
print(f"Done! Excel sheet generated at {output_xlsx}")

---

📂 Project Directory Structure

sheet-me/
├── pyproject.toml         # Package configurations and library dependencies
├── README.md              # This instruction guide
├── run_sample_ocr.py      # Example script to run the pipeline
├── sample_config.json     # Sample table configuration mapping JSON
├── sample_ocr_cache.json  # Sample raw OCR cached results JSON
├── src/
│   └── sheet_me/          # Main library source code
│       ├── __init__.py    # Exposes core classes
│       ├── cli.py         # Command-line interface execution logic
│       ├── deskew.py      # Deskew/straightening calculations
│       ├── ocr.py         # Handles PDF rendering and EasyOCR execution
│       ├── parser.py      # Groups boxes into rows/columns & cleans data
│       └── excel.py       # Handles Excel design themes and formatting
└── tests/
    ├── test_cli.py        # CLI configuration quality assurance tests
    └── test_parser.py     # Parser geometry and cleaning quality assurance tests

---

🧠 Developer API Reference

For developers looking to integrate sheet-me into larger applications:

DeskewManager (deskew.py)

• find_deskew_angle(pil_img, angle_range=5.0, angle_step=0.1) -> float: Finds the deskew angle of the image using horizontal projection profile variance.
• rotate_image(pil_img, angle, background_color=(255, 255, 255)) -> Image.Image: Rotates the image with expanding canvas and white padding.

OCREngine (ocr.py)

• run_ocr_on_image(pil_img) -> list[dict]: Performs OCR and returns structured JSON-serializable bounding boxes.
• extract_pdf_pages_ocr(pdf_path, resolution=150, deskew_manager=None) -> list[dict]: Orchestrates PDF rendering, deskewing, and OCR.
• save_raw_ocr_to_json(data, json_path) & load_raw_ocr_from_json(json_path): Reusable caching utilities to speed up iteration.

TableParser (parser.py)

• compute_box_geometry(box) -> dict: Augments bounding boxes with geometry coordinates (x_min, x_max, y_min, y_max, x_center, y_center, width, height).
• group_boxes_into_rows(boxes, overlap_threshold=0.25) -> list[list[dict]]: Groups boxes into rows using vertical overlap ratio checks.
• classify_columns(row_boxes, columns_definition) -> dict: Groups bounding boxes into cells by column ranges.
• clean_integer(text) -> str: Cleans and normalizes integers.
• clean_name(text) -> str: Cleans names to uppercase, removes junk symbols.
• clean_alphanumeric(text) -> str: Cleans alphanumeric IDs/codes, resolving common OCR confusion patterns.

ExcelGenerator (excel.py)

• save_to_file(data, headers, column_keys, output_path, title, theme, column_alignments): Generates navy-themed professional Excel sheets.