pdfdelta 0.1.0__tar.gz

pdfdelta-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pdfcompare contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pdfdelta-0.1.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: pdfdelta
+Version: 0.1.0
+Summary: Visual diff for born-digital PDFs — highlights changes directly on the original pages
+License: MIT
+Keywords: pdf,diff,compare,highlight,academic,paper
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Text Processing :: General
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyMuPDF>=1.24
+Dynamic: license-file
+
+# pdfdelta
+
+**pdfdelta** is a lightweight visual diff tool for born-digital PDFs.
+
+Given an old and a new version of a PDF, it writes highlights directly onto the original pages so revisions are easy to review: deletions on the old file, additions on the new file.
+
+It is mainly designed for academic papers and technical documents, where small wording changes matter and layout is part of the review process.
+
+<p align="center">
+  <img src="examples/old_marked.png" alt="Old PDF with deletions highlighted" width="48%" />
+  <img src="examples/new_marked.png" alt="New PDF with additions highlighted" width="48%" />
+</p>
+
+## Features
+
+- Highlights changes directly on the original PDF pages
+- Works well for born-digital PDFs such as papers, reports, and drafts
+- Handles multi-column layouts better than plain text diff tools
+- Tries to reduce noisy highlights from simple reflow
+- Keeps the review workflow visual and page-based
+
+## Installation
+
+If you are using the repository directly:
+
+```sh
+pip install git+https://github.com/mli55/pdfdelta.git
+```
+
+## Usage
+
+```sh
+pdfdelta old.pdf new.pdf
+```
+
+This writes two annotated files:
+
+- `old_marked.pdf` — original pages with deletions highlighted
+- `new_marked.pdf` — revised pages with additions highlighted
+
+### Options
+
+| Flag | Default | Description |
+| ---- | ------- | ----------- |
+| `--old-out` | `old_marked.pdf` | Output path for the annotated old PDF |
+| `--new-out` | `new_marked.pdf` | Output path for the annotated new PDF |
+| `--opacity` | `0.35` | Highlight opacity (0.0–1.0) |
+
+## How It Works
+
+```
+ old.pdf    new.pdf
+   │           │
+   ▼           ▼
+┌──────────────────┐
+│  Extract words   │  PyMuPDF: word text + bounding boxes
+└────────┬─────────┘
+         ▼
+┌──────────────────┐
+│  Global diff     │  Flatten all pages → SequenceMatcher
+└────────┬─────────┘
+         ▼
+┌──────────────────┐
+│  Word-level diff │  Per-word & sub-word precision
+└────────┬─────────┘
+         ▼
+┌──────────────────┐
+│  Reflow filter   │  Suppress cross-page / cross-column noise
+└────────┬─────────┘
+         ▼
+┌──────────────────┐
+│  Annotate PDFs   │  Highlights on original pages
+└────────┬─────────┘
+         ▼
+ old_marked.pdf
+ new_marked.pdf
+```
+
+## License
+
+MIT

pdfdelta-0.1.0/README.md

@@ -0,0 +1,81 @@
+# pdfdelta
+
+**pdfdelta** is a lightweight visual diff tool for born-digital PDFs.
+
+Given an old and a new version of a PDF, it writes highlights directly onto the original pages so revisions are easy to review: deletions on the old file, additions on the new file.
+
+It is mainly designed for academic papers and technical documents, where small wording changes matter and layout is part of the review process.
+
+<p align="center">
+  <img src="examples/old_marked.png" alt="Old PDF with deletions highlighted" width="48%" />
+  <img src="examples/new_marked.png" alt="New PDF with additions highlighted" width="48%" />
+</p>
+
+## Features
+
+- Highlights changes directly on the original PDF pages
+- Works well for born-digital PDFs such as papers, reports, and drafts
+- Handles multi-column layouts better than plain text diff tools
+- Tries to reduce noisy highlights from simple reflow
+- Keeps the review workflow visual and page-based
+
+## Installation
+
+If you are using the repository directly:
+
+```sh
+pip install git+https://github.com/mli55/pdfdelta.git
+```
+
+## Usage
+
+```sh
+pdfdelta old.pdf new.pdf
+```
+
+This writes two annotated files:
+
+- `old_marked.pdf` — original pages with deletions highlighted
+- `new_marked.pdf` — revised pages with additions highlighted
+
+### Options
+
+| Flag | Default | Description |
+| ---- | ------- | ----------- |
+| `--old-out` | `old_marked.pdf` | Output path for the annotated old PDF |
+| `--new-out` | `new_marked.pdf` | Output path for the annotated new PDF |
+| `--opacity` | `0.35` | Highlight opacity (0.0–1.0) |
+
+## How It Works
+
+```
+ old.pdf    new.pdf
+   │           │
+   ▼           ▼
+┌──────────────────┐
+│  Extract words   │  PyMuPDF: word text + bounding boxes
+└────────┬─────────┘
+         ▼
+┌──────────────────┐
+│  Global diff     │  Flatten all pages → SequenceMatcher
+└────────┬─────────┘
+         ▼
+┌──────────────────┐
+│  Word-level diff │  Per-word & sub-word precision
+└────────┬─────────┘
+         ▼
+┌──────────────────┐
+│  Reflow filter   │  Suppress cross-page / cross-column noise
+└────────┬─────────┘
+         ▼
+┌──────────────────┐
+│  Annotate PDFs   │  Highlights on original pages
+└────────┬─────────┘
+         ▼
+ old_marked.pdf
+ new_marked.pdf
+```
+
+## License
+
+MIT

pdfdelta-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pdfdelta"
+version = "0.1.0"
+description = "Visual diff for born-digital PDFs — highlights changes directly on the original pages"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+keywords = ["pdf", "diff", "compare", "highlight", "academic", "paper"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Topic :: Text Processing :: General",
+    "Programming Language :: Python :: 3",
+]
+dependencies = [
+    "PyMuPDF>=1.24",
+]
+
+[project.scripts]
+pdfdelta = "pdfdelta.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

pdfdelta-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pdfdelta-0.1.0/src/pdfdelta/__init__.py

@@ -0,0 +1,8 @@
+"""pdfdelta — visual diff for born-digital PDFs."""
+
+from .annotate import apply_annotations
+from .compare import compare_documents
+from .extract import extract_document
+
+__all__ = ["extract_document", "compare_documents", "apply_annotations"]
+__version__ = "0.1.0"

pdfdelta-0.1.0/src/pdfdelta/annotate.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import fitz
+
+from .models import RectTuple
+
+
+def add_highlight(
+    page: fitz.Page,
+    rect_tuple: RectTuple,
+    color: tuple[float, float, float],
+    opacity: float = 0.35,
+) -> None:
+    rect = fitz.Rect(rect_tuple)
+    annot = page.add_highlight_annot(quads=[rect])
+    annot.set_colors(stroke=color)
+    annot.set_opacity(opacity)
+    annot.update()
+
+
+def apply_annotations(
+    input_pdf: str,
+    output_pdf: str,
+    page_to_rects: dict[int, list[RectTuple]],
+    color: tuple[float, float, float],
+    opacity: float = 0.35,
+) -> None:
+    doc = fitz.open(input_pdf)
+    try:
+        for page_index, rects in page_to_rects.items():
+            if page_index >= len(doc):
+                continue
+            page = doc[page_index]
+            for rect in rects:
+                add_highlight(page, rect, color=color, opacity=opacity)
+
+        doc.save(output_pdf, garbage=4, deflate=True)
+    finally:
+        doc.close()

pdfdelta-0.1.0/src/pdfdelta/cli.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from .annotate import apply_annotations
+from .compare import compare_documents
+from .extract import extract_document
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pdfdelta",
+        description="Compare two born-digital PDFs and write highlights back to original PDFs.",
+    )
+    parser.add_argument("old_pdf", help="old/original PDF")
+    parser.add_argument("new_pdf", help="new/revised PDF")
+    parser.add_argument("--old-out", default="old_marked.pdf", help="output annotated old PDF")
+    parser.add_argument("--new-out", default="new_marked.pdf", help="output annotated new PDF")
+    parser.add_argument("--opacity", type=float, default=0.35, help="annotation opacity")
+    return parser
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+
+    old_pdf = str(Path(args.old_pdf))
+    new_pdf = str(Path(args.new_pdf))
+
+    old_pages = extract_document(old_pdf)
+    new_pages = extract_document(new_pdf)
+
+    old_rects, new_rects = compare_documents(old_pages, new_pages)
+
+    apply_annotations(
+        input_pdf=old_pdf,
+        output_pdf=args.old_out,
+        page_to_rects=old_rects,
+        color=(1.0, 0.0, 0.0),
+        opacity=args.opacity,
+    )
+
+    apply_annotations(
+        input_pdf=new_pdf,
+        output_pdf=args.new_out,
+        page_to_rects=new_rects,
+        color=(0.0, 1.0, 0.0),
+        opacity=args.opacity,
+    )
+
+    old_count = sum(len(v) for v in old_rects.values())
+    new_count = sum(len(v) for v in new_rects.values())
+
+    print(f"Done.")
+    print(f"Old annotations: {old_count}")
+    print(f"New annotations: {new_count}")
+    print(f"Wrote: {args.old_out}")
+    print(f"Wrote: {args.new_out}")
+
+
+if __name__ == "__main__":
+    main()

pdfdelta-0.1.0/src/pdfdelta/compare.py

@@ -0,0 +1,443 @@
+from __future__ import annotations
+
+from collections import Counter, defaultdict
+from difflib import SequenceMatcher
+from typing import DefaultDict
+
+from .models import LineBox, PageBox, RectTuple, WordBox
+
+
+def _sub_word_rect(
+    old_word: WordBox, new_word: WordBox,
+) -> tuple[RectTuple, RectTuple]:
+    """Narrow a 1:1 word replacement to only the changed characters.
+
+    Estimates left/right boundaries proportionally based on the shared
+    prefix and suffix lengths.  Falls back to the full word rects when
+    the words are completely different.
+    """
+    a, b = old_word.norm, new_word.norm
+    # Find common prefix length
+    prefix = 0
+    while prefix < len(a) and prefix < len(b) and a[prefix] == b[prefix]:
+        prefix += 1
+    # Find common suffix length (don't overlap with prefix)
+    suffix = 0
+    while (
+        suffix < len(a) - prefix
+        and suffix < len(b) - prefix
+        and a[-(suffix + 1)] == b[-(suffix + 1)]
+    ):
+        suffix += 1
+
+    if prefix == 0 and suffix == 0:
+        return old_word.rect, new_word.rect
+
+    def _trim(rect: RectTuple, text_len: int) -> RectTuple:
+        if text_len == 0:
+            return rect
+        x0, y0, x1, y1 = rect
+        w = x1 - x0
+        new_x0 = x0 + w * (prefix / text_len)
+        new_x1 = x1 - w * (suffix / text_len)
+        if new_x0 >= new_x1:
+            return rect
+        return (new_x0, y0, new_x1, y1)
+
+    return _trim(old_word.rect, len(a)), _trim(new_word.rect, len(b))
+
+
+def _chunk_word_diff(
+    old_chunk: list[LineBox],
+    new_chunk: list[LineBox],
+) -> tuple[list[RectTuple], list[RectTuple]]:
+    """Flatten words across a multi-line chunk and do word-level diff.
+
+    This handles text reflow: when line breaks shift but the actual words
+    are mostly the same, only the truly changed words get highlighted.
+    """
+    old_words = [w for line in old_chunk for w in line.words]
+    new_words = [w for line in new_chunk for w in line.words]
+
+    old_tokens = [w.norm for w in old_words]
+    new_tokens = [w.norm for w in new_words]
+
+    sm = SequenceMatcher(a=old_tokens, b=new_tokens, autojunk=False)
+    old_rects: list[RectTuple] = []
+    new_rects: list[RectTuple] = []
+
+    for tag, i1, i2, j1, j2 in sm.get_opcodes():
+        if tag == "equal":
+            continue
+        if tag == "replace" and (i2 - i1) == 1 and (j2 - j1) == 1:
+            # Single word replaced by single word — use sub-word precision
+            o_r, n_r = _sub_word_rect(old_words[i1], new_words[j1])
+            old_rects.append(o_r)
+            new_rects.append(n_r)
+        else:
+            if tag in ("delete", "replace"):
+                old_rects.extend(w.rect for w in old_words[i1:i2])
+            if tag in ("insert", "replace"):
+                new_rects.extend(w.rect for w in new_words[j1:j2])
+
+    return old_rects, new_rects
+
+
+def _merge_opcodes(opcodes: list[tuple]) -> list[tuple]:
+    """Merge adjacent delete/insert pairs into replace blocks.
+
+    SequenceMatcher often emits a delete immediately followed by an insert
+    (or vice-versa) for text that simply reflowed across lines.  Merging
+    them into a single 'replace' lets _chunk_word_diff handle the reflow
+    and only highlight truly changed words.
+    """
+    merged: list[tuple] = []
+    for op in opcodes:
+        if not merged:
+            merged.append(op)
+            continue
+        prev_tag, pi1, pi2, pj1, pj2 = merged[-1]
+        tag, i1, i2, j1, j2 = op
+        # Merge delete+insert or insert+delete into replace
+        if (
+            {prev_tag, tag} == {"delete", "insert"}
+            or (prev_tag == "replace" and tag in ("delete", "insert"))
+            or (tag == "replace" and prev_tag in ("delete", "insert"))
+        ) and pi2 == i1 and pj2 == j1:
+            merged[-1] = ("replace", pi1, i2, pj1, j2)
+        else:
+            merged.append(op)
+    return merged
+
+
+def _same_line(a: RectTuple | list[float], b: RectTuple) -> bool:
+    """Check if two rects are on the same text line (>50% y overlap)."""
+    y_overlap = min(a[3], b[3]) - max(a[1], b[1])
+    y_height = max(a[3] - a[1], b[3] - b[1])
+    return y_height > 0 and y_overlap / y_height > 0.5
+
+
+def merge_nearby_rects(rects: list[RectTuple], x_gap: float = 10.0) -> list[RectTuple]:
+    """Merge horizontally adjacent rects that share the same line.
+
+    Consecutive highlighted word rects on the same line are combined
+    into a single wide rect.  x_gap should be at least as large as
+    the normal word spacing in the PDF (~3-9 pt typically).
+    """
+    if not rects:
+        return []
+
+    # Sort by vertical midpoint then left edge.
+    sorted_rects = sorted(rects, key=lambda r: ((r[1] + r[3]) / 2, r[0]))
+
+    merged: list[list[float]] = [list(sorted_rects[0])]
+    for r in sorted_rects[1:]:
+        prev = merged[-1]
+        # gap > 0 means r starts after prev ends; gap < 0 means overlap/wrap.
+        # Only merge when gap is within [-x_gap, x_gap] to prevent merging
+        # across columns (where r[0] << prev[2] due to column switch).
+        gap = r[0] - prev[2]
+        if _same_line(prev, r) and -x_gap <= gap <= x_gap:
+            prev[0] = min(prev[0], r[0])
+            prev[2] = max(prev[2], r[2])
+            prev[1] = min(prev[1], r[1])
+            prev[3] = max(prev[3], r[3])
+        else:
+            merged.append(list(r))
+
+    return [(m[0], m[1], m[2], m[3]) for m in merged]
+
+
+def dedupe_rects(rects: list[RectTuple], ndigits: int = 1) -> list[RectTuple]:
+    seen = set()
+    out: list[RectTuple] = []
+    for r in rects:
+        key = tuple(round(v, ndigits) for v in r)
+        if key in seen:
+            continue
+        seen.add(key)
+        out.append(r)
+    return out
+
+
+def _dehyphenate_norms(norms: list[str]) -> list[tuple[str, list[int]]]:
+    """Join hyphenated word pairs into single tokens.
+
+    PDF line-break hyphenation produces e.g. ``"aver-", "age"`` which
+    should be treated as ``"average"`` for matching purposes.
+
+    Returns ``[(dehyphenated_norm, [original_indices]), ...]``.
+    """
+    result: list[tuple[str, list[int]]] = []
+    i = 0
+    while i < len(norms):
+        if norms[i].endswith('-') and len(norms[i]) > 1 and i + 1 < len(norms):
+            joined = norms[i][:-1] + norms[i + 1]
+            result.append((joined, [i, i + 1]))
+            i += 2
+        else:
+            result.append((norms[i], [i]))
+            i += 1
+    return result
+
+
+def _is_hyph_match(a: str, b: str) -> bool:
+    """Check if *a* and *b* are plausibly the same word split by hyphenation.
+
+    Detected patterns:
+    - ``"aver-"`` vs ``"average"``  (line-break hyphen on one side)
+    - ``"particularly"`` vs ``"ticularly"``  (continuation of ``"par-"``
+      on the previous page)
+    """
+    # Pattern 1: one ends with '-', the other starts with that prefix.
+    if a.endswith('-') and len(a) > 2:
+        prefix = a[:-1]
+        if b.startswith(prefix) and len(b) > len(prefix):
+            return True
+    if b.endswith('-') and len(b) > 2:
+        prefix = b[:-1]
+        if a.startswith(prefix) and len(a) > len(prefix):
+            return True
+    # Pattern 2: one token is a suffix of the other (the "continuation"
+    # half of a hyphenated word whose first half sits on the prev page).
+    shorter, longer = (a, b) if len(a) <= len(b) else (b, a)
+    if len(shorter) >= 4 and longer.endswith(shorter) and len(shorter) >= len(longer) * 0.5:
+        return True
+    return False
+
+
+def compare_documents(
+    old_pages: list[PageBox],
+    new_pages: list[PageBox],
+) -> tuple[dict[int, list[RectTuple]], dict[int, list[RectTuple]]]:
+    """Compare two documents using a global (cross-page) diff.
+
+    Flattens all lines from all pages, performs a single global diff,
+    then maps highlighted rects back to their source pages.  This
+    correctly handles text that reflowed across page boundaries.
+
+    Lines whose normalized text appears exactly once in each document
+    are recognised as *moved* (page reflow) and excluded from the diff
+    so that only genuinely changed text gets highlighted.
+    """
+    # Flatten: list of (page_index, LineBox)
+    old_flat: list[tuple[int, LineBox]] = [
+        (p.page_index, line) for p in old_pages for line in p.lines
+    ]
+    new_flat: list[tuple[int, LineBox]] = [
+        (p.page_index, line) for p in new_pages for line in p.lines
+    ]
+
+    old_texts = [line.norm_text for _, line in old_flat]
+    new_texts = [line.norm_text for _, line in new_flat]
+
+    # Frequency counts for move detection: a line appearing exactly once
+    # in each document is the same line, just at a different position.
+    old_counts = Counter(old_texts)
+    new_counts = Counter(new_texts)
+    new_text_set = set(new_texts)
+    old_text_set = set(old_texts)
+
+    def _is_moved(text: str) -> bool:
+        """True when *text* appears exactly once in each document."""
+        return old_counts[text] == 1 and new_counts[text] == 1
+
+    sm = SequenceMatcher(a=old_texts, b=new_texts, autojunk=False)
+    opcodes = _merge_opcodes(list(sm.get_opcodes()))
+
+    # ── First pass: collect candidate highlight words ────────────────
+    # Each candidate is (WordBox, RectTuple, is_subword).
+    # is_subword=True means the rect was trimmed by _sub_word_rect and
+    # represents a genuine character-level change (never suppress these).
+    old_cands: list[tuple[WordBox, RectTuple, bool]] = []
+    new_cands: list[tuple[WordBox, RectTuple, bool]] = []
+
+    for tag, i1, i2, j1, j2 in opcodes:
+        if tag == "equal":
+            continue
+
+        if tag == "delete":
+            for idx in range(i1, i2):
+                _, line = old_flat[idx]
+                if line.norm_text in new_text_set and _is_moved(line.norm_text):
+                    continue
+                for w in line.words:
+                    old_cands.append((w, w.rect, False))
+            continue
+
+        if tag == "insert":
+            for idx in range(j1, j2):
+                _, line = new_flat[idx]
+                if line.norm_text in old_text_set and _is_moved(line.norm_text):
+                    continue
+                for w in line.words:
+                    new_cands.append((w, w.rect, False))
+            continue
+
+        # tag == "replace" — pre-filter moved lines, then word-level diff
+        old_chunk_texts = set(old_texts[i1:i2])
+        new_chunk_texts = set(new_texts[j1:j2])
+
+        moved_old = set()
+        for idx in range(i1, i2):
+            t = old_texts[idx]
+            if t not in new_chunk_texts and t in new_text_set and _is_moved(t):
+                moved_old.add(idx)
+
+        moved_new = set()
+        for idx in range(j1, j2):
+            t = new_texts[idx]
+            if t not in old_chunk_texts and t in old_text_set and _is_moved(t):
+                moved_new.add(idx)
+
+        old_words = [w for i, (_, line) in enumerate(old_flat[i1:i2], i1)
+                     if i not in moved_old for w in line.words]
+        new_words = [w for i, (_, line) in enumerate(new_flat[j1:j2], j1)
+                     if i not in moved_new for w in line.words]
+
+        if not old_words and not new_words:
+            continue
+
+        old_norms = [w.norm for w in old_words]
+        new_norms = [w.norm for w in new_words]
+
+        sm2 = SequenceMatcher(a=old_norms, b=new_norms, autojunk=False)
+        for op_tag, oi1, oi2, oj1, oj2 in sm2.get_opcodes():
+            if op_tag == "equal":
+                continue
+            if op_tag == "replace" and (oi2 - oi1) == 1 and (oj2 - oj1) == 1:
+                o_r, n_r = _sub_word_rect(old_words[oi1], new_words[oj1])
+                old_cands.append((old_words[oi1], o_r, o_r != old_words[oi1].rect))
+                new_cands.append((new_words[oj1], n_r, n_r != new_words[oj1].rect))
+            else:
+                if op_tag in ("delete", "replace"):
+                    for w in old_words[oi1:oi2]:
+                        old_cands.append((w, w.rect, False))
+                if op_tag in ("insert", "replace"):
+                    for w in new_words[oj1:oj2]:
+                        new_cands.append((w, w.rect, False))
+
+    # ── Second pass: page-boundary reflow suppression ──────────────
+    # For each pair of adjacent pages (old_pg P, new_pg P±1), compare
+    # ALL words from both pages using dehyphenation-aware normalization.
+    # Candidate words within contiguous matching runs of ≥ MIN_MATCH
+    # tokens are recognised as reflowed text and suppressed.
+    #
+    # Within-page dehyphenation joins e.g. "aver-"+"age" → "average".
+    # Cross-page hyphenation (where a figure sits between the two halves)
+    # is handled via _is_hyph_match tolerance on 1:1 replace blocks.
+    MIN_MATCH = 2
+
+    suppress_old: set[int] = set()
+    suppress_new: set[int] = set()
+
+    # Index: (page_index, word_rect) → candidate index
+    old_cand_lookup: dict[tuple[int, RectTuple], int] = {}
+    new_cand_lookup: dict[tuple[int, RectTuple], int] = {}
+    old_cand_pages: set[int] = set()
+    new_cand_pages: set[int] = set()
+
+    for i, (w, _, sub) in enumerate(old_cands):
+        if not sub:
+            old_cand_lookup[(w.page_index, w.rect)] = i
+            old_cand_pages.add(w.page_index)
+    for i, (w, _, sub) in enumerate(new_cands):
+        if not sub:
+            new_cand_lookup[(w.page_index, w.rect)] = i
+            new_cand_pages.add(w.page_index)
+
+    def _all_words(pages: list[PageBox], pg: int) -> list[WordBox]:
+        if 0 <= pg < len(pages):
+            return [w for line in pages[pg].lines for w in line.words]
+        return []
+
+    def _suppress(dehyph, start, end, words, lookup, target_set):
+        """Mark candidate words in dehyph[start:end] for suppression."""
+        for k in range(start, end):
+            for wi in dehyph[k][1]:
+                w = words[wi]
+                ci = lookup.get((w.page_index, w.rect))
+                if ci is not None:
+                    target_set.add(ci)
+
+    checked: set[tuple[int, int]] = set()
+    for old_pg in sorted(old_cand_pages):
+        for delta in (1, -1):
+            new_pg = old_pg + delta
+            if new_pg not in new_cand_pages:
+                continue
+            pair = (old_pg, new_pg)
+            if pair in checked:
+                continue
+            checked.add(pair)
+
+            old_words_pg = _all_words(old_pages, old_pg)
+            new_words_pg = _all_words(new_pages, new_pg)
+            if not old_words_pg or not new_words_pg:
+                continue
+
+            old_norms = [w.norm for w in old_words_pg]
+            new_norms = [w.norm for w in new_words_pg]
+
+            # Within-page dehyphenation only (no cross-page peek —
+            # adjacent pages may start with figures, not text continuations)
+            old_dehyph = _dehyphenate_norms(old_norms)
+            new_dehyph = _dehyphenate_norms(new_norms)
+
+            old_tokens = [t for t, _ in old_dehyph]
+            new_tokens = [t for t, _ in new_dehyph]
+
+            sm_b = SequenceMatcher(a=old_tokens, b=new_tokens, autojunk=False)
+            ops = list(sm_b.get_opcodes())
+
+            for oi, (op, bi1, bi2, bj1, bj2) in enumerate(ops):
+                if op == "equal" and (bi2 - bi1) >= MIN_MATCH:
+                    _suppress(old_dehyph, bi1, bi2, old_words_pg,
+                              old_cand_lookup, suppress_old)
+                    _suppress(new_dehyph, bj1, bj2, new_words_pg,
+                              new_cand_lookup, suppress_new)
+                elif op == "replace":
+                    # Boundary tokens of a replace block next to a long
+                    # equal run may be hyphenation artifacts.  E.g.
+                    # "aver-" vs "average" or "particularly" vs "ticularly".
+                    # Leading edge (preceded by equal ≥ MIN_MATCH)
+                    if oi > 0:
+                        p = ops[oi - 1]
+                        if (p[0] == "equal" and (p[2] - p[1]) >= MIN_MATCH
+                                and _is_hyph_match(old_tokens[bi1],
+                                                   new_tokens[bj1])):
+                            _suppress(old_dehyph, bi1, bi1 + 1,
+                                      old_words_pg, old_cand_lookup,
+                                      suppress_old)
+                            _suppress(new_dehyph, bj1, bj1 + 1,
+                                      new_words_pg, new_cand_lookup,
+                                      suppress_new)
+                    # Trailing edge (followed by equal ≥ MIN_MATCH)
+                    if oi < len(ops) - 1:
+                        n = ops[oi + 1]
+                        if (n[0] == "equal" and (n[2] - n[1]) >= MIN_MATCH
+                                and _is_hyph_match(old_tokens[bi2 - 1],
+                                                   new_tokens[bj2 - 1])):
+                            _suppress(old_dehyph, bi2 - 1, bi2,
+                                      old_words_pg, old_cand_lookup,
+                                      suppress_old)
+                            _suppress(new_dehyph, bj2 - 1, bj2,
+                                      new_words_pg, new_cand_lookup,
+                                      suppress_new)
+
+    # ── Map surviving candidates to pages ────────────────────────────
+    old_map: DefaultDict[int, list[RectTuple]] = defaultdict(list)
+    new_map: DefaultDict[int, list[RectTuple]] = defaultdict(list)
+
+    for i, (w, rect, _) in enumerate(old_cands):
+        if i not in suppress_old:
+            old_map[w.page_index].append(rect)
+
+    for i, (w, rect, _) in enumerate(new_cands):
+        if i not in suppress_new:
+            new_map[w.page_index].append(rect)
+
+    return (
+        {k: merge_nearby_rects(dedupe_rects(v)) for k, v in old_map.items()},
+        {k: merge_nearby_rects(dedupe_rects(v)) for k, v in new_map.items()},
+    )

pdfdelta-0.1.0/src/pdfdelta/extract.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import re
+from collections import defaultdict
+
+import fitz
+
+from .models import LineBox, PageBox, WordBox
+
+
+def _normalize(text: str) -> str:
+    return re.sub(r"\s+", " ", text.strip()).lower()
+
+
+def group_words_into_lines(
+    raw_words: list[tuple],
+    page_index: int,
+) -> list[LineBox]:
+    """Group PyMuPDF word tuples into :class:`LineBox` objects.
+
+    Groups by ``(block_no, line_no)`` so that multi-column layouts are
+    handled correctly — words in different columns get separate lines
+    even when they share the same y-coordinate.
+    """
+    groups: defaultdict[tuple[int, int], list[tuple]] = defaultdict(list)
+    for w in raw_words:
+        x0, y0, x1, y1, text, block_no, line_no, word_no = w[:8]
+        if not str(text).strip():
+            continue
+        groups[(int(block_no), int(line_no))].append(
+            (x0, y0, x1, y1, str(text))
+        )
+
+    # Sort by (block_no, line_no) for stable ordering.
+    # Using PyMuPDF's own block ordering keeps line order consistent
+    # between two versions of the same document, even when figures
+    # shift vertically by a few pixels.
+    sorted_keys = sorted(groups.keys())
+
+    lines: list[LineBox] = []
+    for line_idx, key in enumerate(sorted_keys):
+        word_items = sorted(groups[key], key=lambda t: t[0])  # sort by x0
+        line_words: list[WordBox] = []
+        plain_words: list[str] = []
+
+        for word_idx, (x0, y0, x1, y1, text) in enumerate(word_items):
+            word = WordBox(
+                page_index=page_index,
+                line_index=line_idx,
+                word_index=word_idx,
+                text=text,
+                norm=_normalize(text),
+                rect=(x0, y0, x1, y1),
+            )
+            line_words.append(word)
+            plain_words.append(text)
+
+        line_text = " ".join(plain_words)
+        lines.append(
+            LineBox(
+                page_index=page_index,
+                line_index=line_idx,
+                text=line_text,
+                norm_text=_normalize(line_text),
+                words=line_words,
+            )
+        )
+
+    return lines
+
+
+def extract_document(path: str) -> list[PageBox]:
+    doc = fitz.open(path)
+    pages: list[PageBox] = []
+
+    try:
+        for page_index in range(len(doc)):
+            page = doc[page_index]
+            raw_words = page.get_text("words", sort=True)
+            lines = group_words_into_lines(raw_words, page_index=page_index)
+            pages.append(PageBox(page_index=page_index, lines=lines))
+    finally:
+        doc.close()
+
+    return pages

pdfdelta-0.1.0/src/pdfdelta/models.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+RectTuple = tuple[float, float, float, float]
+
+
+@dataclass(frozen=True)
+class WordBox:
+    page_index: int
+    line_index: int
+    word_index: int
+    text: str
+    norm: str
+    rect: RectTuple
+
+
+@dataclass(frozen=True)
+class LineBox:
+    page_index: int
+    line_index: int
+    text: str
+    norm_text: str
+    words: list[WordBox]
+
+
+@dataclass(frozen=True)
+class PageBox:
+    page_index: int
+    lines: list[LineBox]
+
+    @property
+    def text(self) -> str:
+        return "\n".join(line.text for line in self.lines)
+
+    @property
+    def norm_text(self) -> str:
+        return "\n".join(line.norm_text for line in self.lines)

pdfdelta-0.1.0/src/pdfdelta.egg-info/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: pdfdelta
+Version: 0.1.0
+Summary: Visual diff for born-digital PDFs — highlights changes directly on the original pages
+License: MIT
+Keywords: pdf,diff,compare,highlight,academic,paper
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Text Processing :: General
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyMuPDF>=1.24
+Dynamic: license-file
+
+# pdfdelta
+
+**pdfdelta** is a lightweight visual diff tool for born-digital PDFs.
+
+Given an old and a new version of a PDF, it writes highlights directly onto the original pages so revisions are easy to review: deletions on the old file, additions on the new file.
+
+It is mainly designed for academic papers and technical documents, where small wording changes matter and layout is part of the review process.
+
+<p align="center">
+  <img src="examples/old_marked.png" alt="Old PDF with deletions highlighted" width="48%" />
+  <img src="examples/new_marked.png" alt="New PDF with additions highlighted" width="48%" />
+</p>
+
+## Features
+
+- Highlights changes directly on the original PDF pages
+- Works well for born-digital PDFs such as papers, reports, and drafts
+- Handles multi-column layouts better than plain text diff tools
+- Tries to reduce noisy highlights from simple reflow
+- Keeps the review workflow visual and page-based
+
+## Installation
+
+If you are using the repository directly:
+
+```sh
+pip install git+https://github.com/mli55/pdfdelta.git
+```
+
+## Usage
+
+```sh
+pdfdelta old.pdf new.pdf
+```
+
+This writes two annotated files:
+
+- `old_marked.pdf` — original pages with deletions highlighted
+- `new_marked.pdf` — revised pages with additions highlighted
+
+### Options
+
+| Flag | Default | Description |
+| ---- | ------- | ----------- |
+| `--old-out` | `old_marked.pdf` | Output path for the annotated old PDF |
+| `--new-out` | `new_marked.pdf` | Output path for the annotated new PDF |
+| `--opacity` | `0.35` | Highlight opacity (0.0–1.0) |
+
+## How It Works
+
+```
+ old.pdf    new.pdf
+   │           │
+   ▼           ▼
+┌──────────────────┐
+│  Extract words   │  PyMuPDF: word text + bounding boxes
+└────────┬─────────┘
+         ▼
+┌──────────────────┐
+│  Global diff     │  Flatten all pages → SequenceMatcher
+└────────┬─────────┘
+         ▼
+┌──────────────────┐
+│  Word-level diff │  Per-word & sub-word precision
+└────────┬─────────┘
+         ▼
+┌──────────────────┐
+│  Reflow filter   │  Suppress cross-page / cross-column noise
+└────────┬─────────┘
+         ▼
+┌──────────────────┐
+│  Annotate PDFs   │  Highlights on original pages
+└────────┬─────────┘
+         ▼
+ old_marked.pdf
+ new_marked.pdf
+```
+
+## License
+
+MIT

pdfdelta-0.1.0/src/pdfdelta.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+src/pdfdelta/__init__.py
+src/pdfdelta/annotate.py
+src/pdfdelta/cli.py
+src/pdfdelta/compare.py
+src/pdfdelta/extract.py
+src/pdfdelta/models.py
+src/pdfdelta.egg-info/PKG-INFO
+src/pdfdelta.egg-info/SOURCES.txt
+src/pdfdelta.egg-info/dependency_links.txt
+src/pdfdelta.egg-info/entry_points.txt
+src/pdfdelta.egg-info/requires.txt
+src/pdfdelta.egg-info/top_level.txt

pdfdelta-0.1.0/src/pdfdelta.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pdfdelta-0.1.0/src/pdfdelta.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pdfdelta = pdfdelta.cli:main

pdfdelta-0.1.0/src/pdfdelta.egg-info/requires.txt

@@ -0,0 +1 @@
+PyMuPDF>=1.24

pdfdelta-0.1.0/src/pdfdelta.egg-info/top_level.txt

@@ -0,0 +1 @@
+pdfdelta