File size: 5,959 Bytes
5eb40dc
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
"""CPU image clean-up applied before any model sees a page.

Everything here is deterministic OpenCV/PIL work and costs no GPU quota, so it
is always worth doing: a deskewed, adequately-sized page measurably improves
both OCR backends.
"""

from __future__ import annotations

import cv2
import numpy as np
from PIL import Image

__all__ = [
    "prepare",
    "deskew",
    "estimate_skew",
    "to_gray",
    "binarize",
    "estimate_text_height",
    "has_table_rules",
]

#: Below this height most recognisers start dropping characters.
MIN_EDGE = 640
#: Above this the models downscale internally anyway and we only waste memory.
MAX_EDGE = 2400


def to_gray(image: Image.Image) -> np.ndarray:
    """Grayscale ``uint8`` array from any PIL mode."""
    return np.array(image.convert("L"))


def binarize(gray: np.ndarray) -> np.ndarray:
    """Otsu threshold, inverted so text is white on black.

    Inverted is what the morphology in the line segmenter expects, and what
    ``cv2.findContours`` treats as foreground.
    """
    _, binary = cv2.threshold(gray, 0, 255, cv2.THRESH_BINARY_INV + cv2.THRESH_OTSU)
    return binary


def estimate_skew(gray: np.ndarray, max_angle: float = 15.0) -> float:
    """Skew in degrees, positive meaning the page leans counter-clockwise.

    Uses the minimum-area rectangle around all foreground pixels, which is
    cheap and robust for scans.  Returns 0.0 when the estimate is implausible
    (a nearly-blank page, or a rotation large enough to be a real 90-degree
    orientation problem rather than skew).
    """
    binary = binarize(gray)
    # np.where yields (row, col); minAreaRect wants (x, y), so swap the axes.
    # Feeding it (y, x) transposes the page and reports the wrong angle.
    coords = np.column_stack(np.where(binary > 0))[:, ::-1]
    if coords.shape[0] < 50:
        return 0.0
    angle = cv2.minAreaRect(coords.astype(np.float32))[-1]
    # OpenCV reports the angle in (0, 90]; map it to a small signed rotation.
    if angle > 45:
        angle -= 90
    if abs(angle) > max_angle:
        return 0.0
    return float(angle)


def deskew(image: Image.Image, max_angle: float = 15.0) -> Image.Image:
    """Rotate a page upright. Returns the input unchanged for tiny angles."""
    angle = estimate_skew(to_gray(image), max_angle=max_angle)
    if abs(angle) < 0.25:
        return image
    return image.rotate(angle, resample=Image.BICUBIC, expand=True, fillcolor="white")


def estimate_text_height(gray: np.ndarray) -> int:
    """Median height of connected components that look like glyphs.

    Drives the adaptive morphology kernel in the TrOCR line segmenter, which
    the original implementation hardcoded to ``(30, 1)`` -- a width that only
    suits one particular font size.
    """
    binary = binarize(gray)
    n, _, stats, _ = cv2.connectedComponentsWithStats(binary, connectivity=8)
    if n <= 1:
        return 20
    heights = stats[1:, cv2.CC_STAT_HEIGHT]
    areas = stats[1:, cv2.CC_STAT_AREA]
    # Drop specks and full-page frames; what remains is mostly glyphs.
    keep = heights[(areas > 8) & (heights > 4) & (heights < gray.shape[0] * 0.25)]
    if keep.size == 0:
        return 20
    return int(np.median(keep))


def has_table_rules(image: Image.Image, min_lines: int = 3) -> bool:
    """Detect the ruling lines of a table, using morphology alone.

    A text-independent signal, which matters because the reader sometimes
    returns a table as a single run-on line -- leaving nothing columnar to spot
    in the text. Long horizontal and vertical runs of ink are what a ruled
    table has and a page of prose does not, and finding them costs no GPU.
    """
    gray = to_gray(image)
    height, width = gray.shape
    if height < 40 or width < 40:
        return False
    binary = binarize(gray)

    def count_runs(kernel_size: tuple[int, int], axis: int) -> int:
        kernel = cv2.getStructuringElement(cv2.MORPH_RECT, kernel_size)
        found = cv2.morphologyEx(binary, cv2.MORPH_OPEN, kernel, iterations=1)
        contours, _ = cv2.findContours(found, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
        span = width if axis == 0 else height
        return sum(
            1
            for c in contours
            if (cv2.boundingRect(c)[2] if axis == 0 else cv2.boundingRect(c)[3]) > span * 0.3
        )

    horizontal = count_runs((max(width // 8, 12), 1), axis=0)
    if horizontal >= min_lines:
        return True
    # A borderless table often still has column separators, so accept a
    # combination of a couple of rules in each direction.
    vertical = count_runs((1, max(height // 8, 12)), axis=1)
    return horizontal >= 2 and vertical >= 2


def _rescale(image: Image.Image) -> Image.Image:
    """Bring the long edge into a range both backends handle well."""
    w, h = image.size
    longest = max(w, h)
    if longest == 0:
        return image
    if longest < MIN_EDGE:
        factor = MIN_EDGE / longest
    elif longest > MAX_EDGE:
        factor = MAX_EDGE / longest
    else:
        return image
    return image.resize((max(int(w * factor), 1), max(int(h * factor), 1)), Image.LANCZOS)


def _denoise(image: Image.Image) -> Image.Image:
    """Light bilateral filter: removes scan grain without softening strokes."""
    arr = np.array(image.convert("RGB"))
    return Image.fromarray(cv2.bilateralFilter(arr, d=5, sigmaColor=45, sigmaSpace=45))


def prepare(
    image: Image.Image,
    *,
    do_deskew: bool = True,
    do_denoise: bool = True,
    do_rescale: bool = True,
) -> Image.Image:
    """Full pre-processing chain, each step individually skippable.

    Always returns RGB, because both backends expect three channels.
    """
    out = image
    if out.mode not in ("RGB", "L"):
        out = out.convert("RGB")
    if do_deskew:
        out = deskew(out)
    if do_denoise:
        out = _denoise(out)
    if do_rescale:
        out = _rescale(out)
    return out.convert("RGB")