strikethrough-ocr 0.3.3__tar.gz

strikethrough_ocr-0.3.3/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.DS_Store
+*.scan.*
+pages/
+out/

strikethrough_ocr-0.3.3/Makefile

@@ -0,0 +1,18 @@
+.PHONY: all
+all: build test
+
+.PHONY: build
+build:
+	uv build
+
+.PHONY: test
+test:
+	uv run pytest
+
+# uv publish uploads every file in dist/, including builds of old
+# versions; publish only the artifacts of the current version.
+VERSION := $(shell sed -n 's/^version = "\(.*\)"/\1/p' pyproject.toml)
+
+.PHONY: publish
+publish: build test
+	uv publish dist/strikethrough_ocr-$(VERSION)-py3-none-any.whl dist/strikethrough_ocr-$(VERSION).tar.gz

strikethrough_ocr-0.3.3/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.5
+Name: strikethrough-ocr
+Version: 0.3.3
+Summary: OCR for scanned pages that preserves styling: bold, colour, underline and strike-through.
+Author-email: Frank Eickhoff <info@frankeickhoff.de>
+Keywords: contracts,ocr,opencv,scanned-documents,strike-through,strikethrough,tesseract
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics :: Capture :: Scanners
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.11
+Requires-Dist: numpy>=2
+Requires-Dist: opencv-python-headless>=4.11
+Requires-Dist: pytesseract>=0.3.13
+Description-Content-Type: text/markdown
+
+# strikethrough-ocr
+
+Most OCR pipelines silently drop text decorations like color, underline, strike-through. 
+
+StrikethroughOCR tries to preserves them.
+
+## Installation
+
+```sh
+uv tool install strikethrough-ocr    # or: pip install strikethrough-ocr
+```
+
+Tesseract itself must be on `PATH`:
+
+```sh
+brew install tesseract               # macOS
+apt install tesseract-ocr            # Debian/Ubuntu
+```
+
+## Command line
+
+```
+strikethrough-ocr [OPTIONS] INPUT.png
+```
+
+Without options it writes the HTML overlay next to the image:
+
+```sh
+strikethrough-ocr page.png                 # -> page.scan-preview.html (overlay)
+strikethrough-ocr -to html page.png        # -> page.scan.html (clean document)
+strikethrough-ocr -to md page.png          # -> page.scan.md
+strikethrough-ocr page.png -o out/         # choose the output directory
+strikethrough-ocr page.png --stdout        # print instead of writing
+strikethrough-ocr page.png --lang deu+eng  # Tesseract language(s)
+strikethrough-ocr page.png --json          # also write page.scan.json
+strikethrough-ocr page.png --debug         # also write page.debug.png
+strikethrough-ocr page.png -v              # log second-pass OCR decisions
+```
+
+| option | effect |
+|---|---|
+| `-to {preview,html,md}` | output format; `preview` (default) writes the overlay as `<name>.scan-preview.html`, `html` writes the clean document as `<name>.scan.html`, `md` writes `<name>.scan.md` |
+| `-o`, `--out-dir` | output directory (default: next to the image) |
+| `--stdout` | print the output instead of writing a file |
+| `--lang` | Tesseract language(s), e.g. `deu+eng` (default `eng`) |
+| `--psm` | Tesseract page segmentation mode (default 3) |
+| `--bold-factor` | stroke width relative to regular text that counts as bold (default 1.2) |
+| `--json` | also write `<name>.scan.json` with the page model as records |
+| `--debug` | also write `<name>.debug.png` with the detections drawn on the scan |
+| `--min-conf` | `-to html`, `-to md`: drop words below this OCR confidence |
+| `--no-color` | `-to html`, `-to md`: do not emit colour spans |
+| `--no-headings` | `-to html`, `-to md`: large text stays a paragraph |
+| `-v`, `--verbose` | log second-pass OCR and layout decisions |
+
+The HTML overlay references the scan by relative path for its slider, so
+keep the two files together or the slider shows nothing.
+
+## Library
+
+```python
+from strikethrough_ocr import process, render_html, html_to_markdown, \
+    html_to_document_html
+
+model = process("page.png", lang="eng")           # run the OCR pipeline
+overlay = render_html(model, "page", "page.png")  # styled HTML overlay
+md = html_to_markdown(overlay)                    # Markdown in reading order
+doc = html_to_document_html(overlay)              # clean document HTML
+```
+
+`process()` returns a `PageModel`: words (text, box, baseline, font size,
+colour, bold, underline, strike, decoration colour, confidence), table
+rules, decoration strokes and graphics. `model_to_json()` turns it into
+plain records; `draw_debug()` paints the detections onto the scan image.
+
+## Development
+
+```sh
+uv sync --group dev          # install with the test dependencies
+uv run pytest                # unit tests and golden files
+UPDATE_GOLDENS=1 uv run pytest   # rewrite tests/golden and the overlay fixture
+```
+
+The golden tests pin all three renderings of one synthetic fixture page
+(`tests/conftest.py` builds it): the overlay it renders must equal
+`tests/fixtures/page.overlay.html`, and the Markdown and document HTML
+produced from that fixture must equal the files under `tests/golden/`.
+After a deliberate change to a renderer, regenerate them and review the
+diff. One end-to-end test runs the real pipeline and is skipped when no
+`tesseract` binary is on PATH.
+
+## How it works
+
+1. **Ink mask.** The page is thresholded on each pixel's *distance from
+   white*, `255 − min(B, G, R)`, so black and coloured ink are both caught.
+   The glyph size measured on this mask sets the working scale: a scan
+   whose print is smaller than the 300 dpi reference is enlarged (up to 4x)
+   before anything else, because Tesseract and every stroke measure need
+   the pixels. Highlighter bands pass the ink threshold too; they are
+   recognised as *bright, broad* fills — every print ink is dark, and no
+   stroke of print is as tall as a marker band — and whitened away, so OCR
+   sees paper while the letters on top of them stay.
+2. **Straight strokes.** Morphological opening finds long horizontal and
+   vertical strokes. A stroke with clear paper on both sides is a **table
+   rule**; every other horizontal stroke is a **decoration candidate**
+   (underline or strike-through). The paper test follows the stroke's ink
+   column by column, so a slightly slanted strike-through does not pass
+   for a rule. A stroke crossed by vertical rules belongs to a table
+   lattice: it is split at the crossings, and only a piece whose glyphs
+   pass through it (a strike drawn flush onto a row boundary fuses with
+   it into one line) stays a decoration. Length is deliberately no
+   criterion — a struck-through paragraph line is as long as a rule.
+3. **OCR.** Strikes are removed in two ways (Telea inpainting and
+   column-wise erasure, which fail on different glyphs) and Tesseract reads
+   the cleaned page as hOCR, which carries a baseline and font size per row.
+   Weak lines are cut out and read again in isolation.
+4. **Per-word style.** Colour is the median of the *darkest* ink in the
+   word box (darkest by luminance, so the fringe where a glyph blends into
+   a marker or the paper does not vote); a decoration's colour comes from
+   the stroke's own pixels, or the glyphs a red line crosses would outvote
+   the line. Bold compares the measured stroke width (2 × area / perimeter of the
+   word's core ink) against a regular-weight model fitted to the page.
+   Decoration strokes are assigned to the words they span: through the
+   x-height it is a strike, at the baseline an underline. Struck lines are
+   re-read on both cleaned variants and the most confident reading wins.
+5. **Graphics.** Oversized coloured lettering (logos) and ink no confident
+   word claims are cropped from the scan and embedded as PNG data URIs.
+
+In the Markdown output, connected rules become tables (merged cells hold
+their content in the top-left grid cell), large text becomes headings,
+bold is `**text**`, strike-through `~~text~~`, underline `<u>text</u>`
+and colour `<span style="color:#rrggbb">…</span>`; colour and underline
+have no Markdown syntax, so they are inline HTML. The document HTML
+output shares the same layout analysis and writes it the way pandoc
+would: `<p>`, `<h1..h3>` with an id, `<table>` with a `<colgroup>`,
+`<strong>`/`<del>`/`<u>`/`<span>` inline, and consecutive paragraphs
+labelled `(vi)`, `(b)` or `3.` folded into `<ol start type>` lists —
+unless the label itself is struck through, because deleted text keeps
+its literal label.
+
+## Limits and assumptions
+
+* Geometry constants are set for a 300 dpi scan and scaled to the page's
+  *measured* glyph size; a scan with smaller print is enlarged internally
+  (up to 4x) first. Below roughly 8 px of x-height there is not enough
+  signal left even so, and the bold measure goes first.
+* The page is assumed to be deskewed; a rotated page breaks the rule
+  detection.
+* Bold is relative: a page set entirely in bold has no regular reference
+  and renders as regular. Italic is not detected.
+* Underline and strike-through are found as straight strokes at least
+  40 px long (at 300 dpi); a wavy or hand-drawn line is missed, and a
+  heavy or doubled strike hides too much of the glyphs for the text to be
+  recovered. A marker stroke as tall as the text it covers is taken for a
+  highlight, not a strike.
+* The HTML overlay is a *reproduction of the page*, not a document: words
+  are absolutely positioned and the reading order is Tesseract's. The
+  document HTML and Markdown outputs are the document view.

strikethrough_ocr-0.3.3/README.md

@@ -0,0 +1,157 @@
+# strikethrough-ocr
+
+Most OCR pipelines silently drop text decorations like color, underline, strike-through. 
+
+StrikethroughOCR tries to preserves them.
+
+## Installation
+
+```sh
+uv tool install strikethrough-ocr    # or: pip install strikethrough-ocr
+```
+
+Tesseract itself must be on `PATH`:
+
+```sh
+brew install tesseract               # macOS
+apt install tesseract-ocr            # Debian/Ubuntu
+```
+
+## Command line
+
+```
+strikethrough-ocr [OPTIONS] INPUT.png
+```
+
+Without options it writes the HTML overlay next to the image:
+
+```sh
+strikethrough-ocr page.png                 # -> page.scan-preview.html (overlay)
+strikethrough-ocr -to html page.png        # -> page.scan.html (clean document)
+strikethrough-ocr -to md page.png          # -> page.scan.md
+strikethrough-ocr page.png -o out/         # choose the output directory
+strikethrough-ocr page.png --stdout        # print instead of writing
+strikethrough-ocr page.png --lang deu+eng  # Tesseract language(s)
+strikethrough-ocr page.png --json          # also write page.scan.json
+strikethrough-ocr page.png --debug         # also write page.debug.png
+strikethrough-ocr page.png -v              # log second-pass OCR decisions
+```
+
+| option | effect |
+|---|---|
+| `-to {preview,html,md}` | output format; `preview` (default) writes the overlay as `<name>.scan-preview.html`, `html` writes the clean document as `<name>.scan.html`, `md` writes `<name>.scan.md` |
+| `-o`, `--out-dir` | output directory (default: next to the image) |
+| `--stdout` | print the output instead of writing a file |
+| `--lang` | Tesseract language(s), e.g. `deu+eng` (default `eng`) |
+| `--psm` | Tesseract page segmentation mode (default 3) |
+| `--bold-factor` | stroke width relative to regular text that counts as bold (default 1.2) |
+| `--json` | also write `<name>.scan.json` with the page model as records |
+| `--debug` | also write `<name>.debug.png` with the detections drawn on the scan |
+| `--min-conf` | `-to html`, `-to md`: drop words below this OCR confidence |
+| `--no-color` | `-to html`, `-to md`: do not emit colour spans |
+| `--no-headings` | `-to html`, `-to md`: large text stays a paragraph |
+| `-v`, `--verbose` | log second-pass OCR and layout decisions |
+
+The HTML overlay references the scan by relative path for its slider, so
+keep the two files together or the slider shows nothing.
+
+## Library
+
+```python
+from strikethrough_ocr import process, render_html, html_to_markdown, \
+    html_to_document_html
+
+model = process("page.png", lang="eng")           # run the OCR pipeline
+overlay = render_html(model, "page", "page.png")  # styled HTML overlay
+md = html_to_markdown(overlay)                    # Markdown in reading order
+doc = html_to_document_html(overlay)              # clean document HTML
+```
+
+`process()` returns a `PageModel`: words (text, box, baseline, font size,
+colour, bold, underline, strike, decoration colour, confidence), table
+rules, decoration strokes and graphics. `model_to_json()` turns it into
+plain records; `draw_debug()` paints the detections onto the scan image.
+
+## Development
+
+```sh
+uv sync --group dev          # install with the test dependencies
+uv run pytest                # unit tests and golden files
+UPDATE_GOLDENS=1 uv run pytest   # rewrite tests/golden and the overlay fixture
+```
+
+The golden tests pin all three renderings of one synthetic fixture page
+(`tests/conftest.py` builds it): the overlay it renders must equal
+`tests/fixtures/page.overlay.html`, and the Markdown and document HTML
+produced from that fixture must equal the files under `tests/golden/`.
+After a deliberate change to a renderer, regenerate them and review the
+diff. One end-to-end test runs the real pipeline and is skipped when no
+`tesseract` binary is on PATH.
+
+## How it works
+
+1. **Ink mask.** The page is thresholded on each pixel's *distance from
+   white*, `255 − min(B, G, R)`, so black and coloured ink are both caught.
+   The glyph size measured on this mask sets the working scale: a scan
+   whose print is smaller than the 300 dpi reference is enlarged (up to 4x)
+   before anything else, because Tesseract and every stroke measure need
+   the pixels. Highlighter bands pass the ink threshold too; they are
+   recognised as *bright, broad* fills — every print ink is dark, and no
+   stroke of print is as tall as a marker band — and whitened away, so OCR
+   sees paper while the letters on top of them stay.
+2. **Straight strokes.** Morphological opening finds long horizontal and
+   vertical strokes. A stroke with clear paper on both sides is a **table
+   rule**; every other horizontal stroke is a **decoration candidate**
+   (underline or strike-through). The paper test follows the stroke's ink
+   column by column, so a slightly slanted strike-through does not pass
+   for a rule. A stroke crossed by vertical rules belongs to a table
+   lattice: it is split at the crossings, and only a piece whose glyphs
+   pass through it (a strike drawn flush onto a row boundary fuses with
+   it into one line) stays a decoration. Length is deliberately no
+   criterion — a struck-through paragraph line is as long as a rule.
+3. **OCR.** Strikes are removed in two ways (Telea inpainting and
+   column-wise erasure, which fail on different glyphs) and Tesseract reads
+   the cleaned page as hOCR, which carries a baseline and font size per row.
+   Weak lines are cut out and read again in isolation.
+4. **Per-word style.** Colour is the median of the *darkest* ink in the
+   word box (darkest by luminance, so the fringe where a glyph blends into
+   a marker or the paper does not vote); a decoration's colour comes from
+   the stroke's own pixels, or the glyphs a red line crosses would outvote
+   the line. Bold compares the measured stroke width (2 × area / perimeter of the
+   word's core ink) against a regular-weight model fitted to the page.
+   Decoration strokes are assigned to the words they span: through the
+   x-height it is a strike, at the baseline an underline. Struck lines are
+   re-read on both cleaned variants and the most confident reading wins.
+5. **Graphics.** Oversized coloured lettering (logos) and ink no confident
+   word claims are cropped from the scan and embedded as PNG data URIs.
+
+In the Markdown output, connected rules become tables (merged cells hold
+their content in the top-left grid cell), large text becomes headings,
+bold is `**text**`, strike-through `~~text~~`, underline `<u>text</u>`
+and colour `<span style="color:#rrggbb">…</span>`; colour and underline
+have no Markdown syntax, so they are inline HTML. The document HTML
+output shares the same layout analysis and writes it the way pandoc
+would: `<p>`, `<h1..h3>` with an id, `<table>` with a `<colgroup>`,
+`<strong>`/`<del>`/`<u>`/`<span>` inline, and consecutive paragraphs
+labelled `(vi)`, `(b)` or `3.` folded into `<ol start type>` lists —
+unless the label itself is struck through, because deleted text keeps
+its literal label.
+
+## Limits and assumptions
+
+* Geometry constants are set for a 300 dpi scan and scaled to the page's
+  *measured* glyph size; a scan with smaller print is enlarged internally
+  (up to 4x) first. Below roughly 8 px of x-height there is not enough
+  signal left even so, and the bold measure goes first.
+* The page is assumed to be deskewed; a rotated page breaks the rule
+  detection.
+* Bold is relative: a page set entirely in bold has no regular reference
+  and renders as regular. Italic is not detected.
+* Underline and strike-through are found as straight strokes at least
+  40 px long (at 300 dpi); a wavy or hand-drawn line is missed, and a
+  heavy or doubled strike hides too much of the glyphs for the text to be
+  recovered. A marker stroke as tall as the text it covers is taken for a
+  highlight, not a strike.
+* The HTML overlay is a *reproduction of the page*, not a document: words
+  are absolutely positioned and the reading order is Tesseract's. The
+  document HTML and Markdown outputs are the document view.

strikethrough_ocr-0.3.3/___dev/.notes

@@ -0,0 +1,2 @@
+registered_at="2026-09-23 10:12:48"
+source_path="/Users/frankeickhoff/dev/contract-dsl/strikethrough-ocr"

strikethrough_ocr-0.3.3/___dev/COMMIT_CHANGES.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+# Commit the remaining working tree of the strikethrough-ocr repository.
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+git add src/strikethrough_ocr/strikethrough_ocr.py
+git commit -m "fix: add the renamed CLI module
+
+The console script entry point already refers to
+strikethrough_ocr.strikethrough_ocr, but the renamed module file itself
+was never committed."
+
+git add tests/conftest.py
+git add tests/test_golden.py
+git add tests/test_scan_ink.py
+git add tests/test_scan_geometry.py
+git add tests/test_document.py
+git add tests/test_cli.py
+git add tests/test_integration.py
+git add tests/fixtures/page.overlay.html
+# the golden files match the *.scan.* ignore pattern, so they are added explicitly
+git add -f tests/golden/page.scan.md
+git add -f tests/golden/page.scan.html
+git commit -m "test: add unit tests, fixtures and golden files
+
+A synthetic fixture page pins all three renderings: the overlay must
+match tests/fixtures and the Markdown and document HTML must match
+tests/golden. Unit tests cover ink analysis, stroke classification,
+decoration assignment and the CLI; an end-to-end test skips without
+tesseract."

strikethrough_ocr-0.3.3/___dev/NOTES.md

@@ -0,0 +1,25 @@
+
+These are my personal notes.
+The ___dev/ folder is entirely for development.
+For commits or generated documentation, never mention any planning or investigation details as described in ___dev/.
+
+🤖 Please ignore everything below the next line.
+
+
+---
+
+install from local
+
+    uv tool install . 2>&1 | tail -3 && which strikethrough-ocr && strikethrough-ocr --version
+
+    uv tool install --force .
+    
+---
+
+    cd strikethrough-ocr
+
+    uv build
+    
+    uv publish --token pypi-<your-api-token>    # token from pypi.org/manage/account/token
+
+    ~/.pypirc

strikethrough_ocr-0.3.3/demo.sh

@@ -0,0 +1,18 @@
+#!/bin/bash
+
+mkdir -p ./out
+rm -rf ./out/*
+
+for INPUT in $(find ./pages -type f \( -name '*.png' -o -name '*.jpg' \) | sort); do
+    echo $INPUT
+    strikethrough-ocr ${INPUT} --debug --json -o ./out
+    strikethrough-ocr ${INPUT} -to html -o ./out
+    strikethrough-ocr ${INPUT} -to md -o ./out
+done
+
+for INPUT in $(find ./examples -type f \( -name '*.png' -o -name '*.jpg' \) | sort); do
+    echo $INPUT
+    strikethrough-ocr ${INPUT} --debug --json -o ./out
+    strikethrough-ocr ${INPUT} -to html -o ./out
+    strikethrough-ocr ${INPUT} -to md -o ./out
+done

strikethrough_ocr-0.3.3/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "strikethrough-ocr"
+version = "0.3.3"
+description = "OCR for scanned pages that preserves styling: bold, colour, underline and strike-through."
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [
+    { name = "Frank Eickhoff", email = "info@frankeickhoff.de" },
+]
+keywords = ["ocr", "strikethrough", "strike-through", "tesseract", "opencv", "scanned-documents", "contracts"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Graphics :: Capture :: Scanners",
+    "Topic :: Scientific/Engineering :: Image Recognition",
+    "Topic :: Text Processing :: Markup :: Markdown",
+]
+dependencies = [
+    "opencv-python-headless>=4.11",
+    "numpy>=2",
+    "pytesseract>=0.3.13",
+]
+
+[project.scripts]
+strikethrough-ocr = "strikethrough_ocr.strikethrough_ocr:main"
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/strikethrough_ocr"]

strikethrough_ocr-0.3.3/src/strikethrough_ocr/__init__.py

@@ -0,0 +1,42 @@
+"""strikethrough-ocr -- OCR for scanned pages that preserves styling.
+
+Library use:
+
+    from strikethrough_ocr import process, render_html, html_to_markdown
+
+    model = process("page.png", lang="eng")          # run the OCR pipeline
+    overlay = render_html(model, "page", "page.png") # styled HTML overlay
+    md = html_to_markdown(overlay)                   # Markdown in reading order
+    doc = html_to_document_html(overlay)             # clean document HTML
+"""
+
+__version__ = "0.3.3"
+
+from .scan import (
+    PageModel,
+    draw_debug,
+    model_to_json,
+    process,
+    render_html,
+)
+from .markdown import (
+    html_to_document_html,
+    html_to_markdown,
+    page_to_html,
+    page_to_markdown,
+    parse_page,
+)
+
+__all__ = [
+    "__version__",
+    "PageModel",
+    "draw_debug",
+    "model_to_json",
+    "process",
+    "render_html",
+    "html_to_document_html",
+    "html_to_markdown",
+    "page_to_html",
+    "page_to_markdown",
+    "parse_page",
+]