DEV Community: JAGADEESH .M

Why PDF Bounding Box Coordinates Break in Python (and How to Fix Them)

JAGADEESH .M — Fri, 06 Nov 2026 12:24:36 +0000

If you have ever built an automated document processing pipeline—such as extracting data from tax returns, invoices, insurance claims, or contracts—you have almost certainly hit the coordinate drift nightmare.

You carefully define a bounding box for an input field:

bbox = [100.0, 150.0, 350.0, 180.0]  # [x0, y0, x1, y1]

You run your extraction code, and:

Half the text is cut off.
Words from the row above or below bleed into your output.
On rotated pages or cropped scans, your bounding boxes end up completely misplaced.

In this article, we'll examine why PDF coordinate extraction is so error-prone in Python, the mathematical root causes behind coordinate drift, and how to achieve 100% deterministic spatial extraction.

The Root Causes: Why PDF Coordinates Drift

1. The Inverted Origin Trap (Bottom-Left vs. Top-Left)

According to the official Adobe PDF specification (ISO 32000), the default PDF user coordinate system places the coordinate origin (0, 0) at the BOTTOM-LEFT corner of the physical page:

$X$ increases from left to right.
$Y$ increases from bottom to top ($Y_{\text{up}}$).

However, computer screens, GUI canvases, and modern computer vision tools (OpenCV, PIL, browser viewports) place (0, 0) at the TOP-LEFT corner:

$X$ increases from left to right.
$Y$ increases from top to bottom ($Y_{\text{down}}$).

$$\text{Screen } Y = \text{Page Height} - \text{PDF } Y$$

If an extraction library does not rigorously track page height and media boundaries, a coordinate transformation will silently invert or shift your text bounding boxes.

2. The MediaBox vs. CropBox Offset Trap

A standard PDF page does not have just one boundary. It defines up to five distinct bounding boxes:

MediaBox: The full physical dimensions of the medium (e.g. letter paper: 612 × 792 points).
CropBox: The visible, printable region of the page.
BleedBox / TrimBox / ArtBox: Printing and formatting boundaries.

Many government forms and scanned documents define a MediaBox starting at (0, 0), but a CropBox with non-zero offsets:

/MediaBox [0 0 612 792]
/CropBox [36 45 576 747]

Pure-Python parsers frequently calculate character offsets relative to MediaBox instead of CropBox. If the user visualizes the PDF in a viewer (which renders the CropBox), their defined coordinates will be offset by 30 to 50 points from where the text actually lives!

3. Font Metrics and Line Leading vs. Glyph Ink

When extracting text by bounding box, what is the boundary of a word?

Glyph Ink Boundary: The exact outline of the visible black pixels.
Font Em-Box Boundary: The typographic box including font ascender, descender, and line leading.

If an extraction tool uses only character ink outlines, bounding boxes around lowercase text (e.g., "acme") will have completely different vertical heights than text with tall ascenders or descenders (e.g., "plymouth"). This makes fixed-height template extraction brittle.

The Solution: Native C++ Layout Engines

To solve coordinate drift permanently, modern extraction pipelines rely on production-grade C++ PDF rendering engines (like Google's PDFium, the battle-tested engine inside Google Chrome) rather than heuristic pure-Python tokenizers.

Google PDFium parses native TrueType/OpenType font tables, calculates exact transform matrices, and provides native device-to-page coordinate transformations.

Practical Implementation with `openfitz`

To make spatial text extraction and visual validation straightforward in Python, we built openfitz—a lightweight, permissive (MIT-licensed) library powered directly by Google PDFium.

1. Installation

pip install openfitz

2. Extracting Text from an Exact Bounding Box

With openfitz, coordinates use standard top-left (x0, y0, x1, y1) points, automatically normalized against CropBox boundaries:

import fitz

# Open document
doc = fitz.open("tax_return.pdf")
page = doc[0]

# Define field bounding box in points: [x0, y0, x1, y1]
ein_rect = fitz.Rect(300, 100, 500, 130)

# Extract text clipped strictly to this rectangle
ein_text = page.get_text("text", clip=ein_rect).strip()
print("Extracted EIN:", ein_text)
# Output: '12-3456789'

doc.close()

3. Hierarchical Spatial Inspection (`blocks`, `lines`, `spans`)

When you need to reconstruct complex multi-column layouts, inspect font sizes, or parse tables:

import fitz

doc = fitz.open("invoice.pdf")
page = doc[0]

# Inspect structured text hierarchy
page_dict = page.get_text("dict")

for block in page_dict["blocks"]:
    print(f"\nBlock #{block['number']} at {block['bbox']}")
    for line in block["lines"]:
        for span in line["spans"]:
            print(f"  Text: '{span['text']}' | Font: {span['font']} ({span['size']}pt)")

Every span contains:

bbox: (x0, y0, x1, y1) in top-left screen points.
font: Font family name.
size: Typographic font size.
text: Extracted UTF-8 string.

4. Detecting Checkboxes and Marks via Raster Analysis

One of the hardest problems in form automation is verifying whether a checkbox is checked or blank. Vector text extractors see nothing because checkboxes are often drawn as vector path squares ([ ]) or images.

openfitz solves this by allowing direct rasterization of the target rectangle to memory:

import fitz

def is_checkbox_checked(page, box_coords, threshold=0.08) -> bool:
    """
    Renders the checkbox region and measures darkness ratio.
    """
    # 1. Target the checkbox area
    box_rect = fitz.Rect(*box_coords)

    # 2. Render at 2x resolution for crisp pixel sampling
    mat = fitz.Matrix(2, 2)
    pix = page.get_pixmap(matrix=mat, clip=box_rect)

    # 3. Analyze raw packed RGB pixel samples
    img_data = pix.samples
    total_pixels = len(img_data) // 3

    # Count dark pixels (grayscale value < 200)
    dark_pixels = sum(1 for i in range(0, len(img_data), 3) if img_data[i] < 200)
    darkness_ratio = dark_pixels / total_pixels if total_pixels > 0 else 0

    return darkness_ratio > threshold

# Usage:
doc = fitz.open("w2_form.pdf")
page = doc[0]

# Checkbox at (50, 250, 65, 265)
checked = is_checkbox_checked(page, [50, 250, 65, 265])
print("Is Box Checked?", checked)

Because rendering is powered by Google's native rasterizer, visual pixel counts match screen rendering with 100% precision.

Conclusion & Best Practices

When building automated PDF spatial extraction:

Always standardize on top-left origin: Normalize all templates to x0, y0, x1, y1 relative to visible page dimensions.
Account for non-zero CropBox offsets: Never assume (0, 0) is the physical printable origin.
Combine vector text with raster analysis: Use text extraction for typed inputs and raster darkness ratios for checkboxes and signatures.

PyPI: pypi.org/project/openfitz
GitHub: github.com/jagadeesh88705/openfitz
License: MIT (Permissive & Commercial-friendly)

How to Handle Duplicate Alembic Migration Numbers When Developers Work in Parallel

JAGADEESH .M — Fri, 06 Nov 2026 04:14:29 +0000

If your engineering team uses SQLAlchemy and Alembic to manage database migrations, you have almost certainly encountered this painful scenario:

Two developers branch off main at the same time to build different features. Both developers generate an Alembic migration. When their branches are merged or tested on a shared database, Alembic explodes:

alembic.util.exc.CommandError: Multiple head revisions are present for given argument 'head'; please specify a revision or 'heads'

Or worse, if you use sequential prefixes like 0001_, 0002_, both developers end up with a file starting with 0004_, causing duplicate revision conflicts, broken CI pipelines, and corrupted shared dev databases.

In this article, we’ll explore why this happens, why the standard alembic merge command is often frustrating, and how to automate the resolution cleanly.

The Root Cause: Why Parallel Branching Breaks Migration Chains

Alembic represents migration history as a Directed Acyclic Graph (DAG) where each migration script points to its parent via down_revision:

0001_initial.py  <-  0002_users.py  <-  0003_profiles.py

The Conflict Scenario:

Developer A branches off main at revision 0003. They generate migration 0004_add_orders.py (down_revision = '0003').
Developer B branches off main at the exact same time. They generate migration 0004_add_inventory.py (down_revision = '0003').

Now your migration tree has forked into two heads:

                        ┌──> 0004_add_orders.py (HEAD 1)
0003_profiles.py ───────┤
                        └──> 0004_add_inventory.py (HEAD 2)

When either developer (or your CI/CD pipeline) runs alembic upgrade head, Alembic halts immediately because it does not know which branch to apply first.

Why Standard `alembic merge` is Problematic for Sequential Migrations

Alembic provides a native command:

alembic merge heads -m "merge orders and inventory"

While this works, it introduces several major headaches for development teams:

Cluttered "Diamond" Merge Graph: It creates a dedicated merge migration file (0005_merge_heads.py) that contains no actual schema changes—just down_revision = ('0004_orders', '0004_inventory'). Over a few months with an active team, your migration tree becomes a tangled web of diamond merge nodes.
No File Renumbering: If your team prefers human-readable sequence prefixes (0001, 0002, 0003), alembic merge does not renumber the conflicting files. You are left with two 0004_ files permanently in your repository.
Shared Database Desynchronization: If Developer A tests on a shared dev database, the database gets stamped with 0004_orders. When Developer B pulls the shared database to test their branch, Alembic crashes with Can't locate revision identified by '0004_orders' because Developer B’s local branch doesn't have Developer A’s file yet.

The Alternative: Automated In-Place Rebase with `alembic-autoseq`

Instead of creating diamond merge nodes or manually renaming files and editing down_revision by hand, the ideal workflow is an automated rebase:

0003_profiles.py -> 0004_add_orders.py -> 0005_add_inventory.py (HEAD)

This is what alembic-autoseq does.

How It Works:

AST Parsing: It safely inspects your versions/ folder using Python's native ast module (without executing migration code or creating database side-effects).
Conflict Detection: It identifies multiple heads, duplicate revision IDs, and sequential prefix collisions.
Atomic Rebase: It determines which migration belongs to the active branch, updates down_revision to the latest upstream head, auto-increments the sequence number (0004_add_inventory.py $\rightarrow$ 0005_add_inventory.py), and renames the file on disk.
In-Memory Cache Reload: It refreshes Alembic's in-memory RevisionMap on the fly so the migration command completes without error.

Step-by-Step Implementation

Step 1: Install the Package

pip install alembic-autoseq

Step 2: Add the 1-Line Guard to `alembic/env.py`

Inside your project's alembic/env.py:

import alembic_autoseq

def run_migrations_online():
    connectable = engine_from_config(...)

    with connectable.connect() as connection:
        # Intercepts and heals parallel branch conflicts before Alembic runs
        alembic_autoseq.guard(connection=connection, auto_heal=True)

        context.configure(connection=connection, target_metadata=target_metadata)
        with context.begin_transaction():
            context.run_migrations()
        connection.commit()

Step 3: Run Your Normal Migration

Now, developers simply run:

alembic upgrade head

If a colleague merged a migration while they were working, alembic-autoseq automatically linearizes the branch migration and applies it cleanly.

Adding a CI/CD Quality Gate

To ensure that no conflicting or multi-head migrations are ever merged into main, you can add a check to your GitHub Actions pipeline:

# .github/workflows/migrations.yml
name: Migration Check

on: [pull_request]

jobs:
  verify-migrations:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - run: pip install alembic-autoseq
      - run: alembic-autoseq check

If a Pull Request introduces a duplicate revision ID or a multi-head fork, alembic-autoseq check will exit with code 1 and display a clear error message in the PR logs.

When NOT to Rebase

Production Migrations: Never modify migrations that have already been applied to your production database. alembic-autoseq is strictly designed for unmerged, local feature branches before code is merged into your production release branch.
Intentional Multi-Database Branching: If your infrastructure deliberately uses separate Alembic branches for multi-tenant or multi-database architectures, stick to Alembic’s native branching.

Conclusion

Parallel development shouldn't mean wasting 30 minutes resolving migration merge conflicts or cluttering your Git history with empty merge commits. By adopting an automated sequential rebase strategy, teams can maintain clean, linear database migration histories effortlessly.

📦 PyPI: pip install alembic-autoseq
💻 GitHub: https://github.com/jagadeesh88705/alembic_autoseq