1"""Tables on scanned images: ruled grids found from their lines, tables without rules from word positions.
2Shared with the document-to-markdown Actor (src/convert.py there); keep both copies in step."""
3from __future__ import annotations
4
5import os
6import re
7import statistics
8import subprocess
9import tempfile
10
11import numpy as np
12import pytesseract
13from PIL import Image, ImageFilter, ImageOps
14
15
16class ConversionError(Exception):
17 pass
18
19
20BL_MIN_ROWS = 3
21
22BL_MIN_COLS = 3
23
24GRID_DARK = 170
25
26GRID_MIN_ROWS = 2
27
28GRID_MIN_COLS = 2
29
30_DIGIT_LOOKALIKE = str.maketrans({'З': '3', 'з': '3', 'О': '0', 'о': '0', 'O': '0', 'o': '0', 'l': '1', 'I': '1',
31 '|': '1', 'б': '6', 'Б': '6'})
32
33_NUMERO = re.compile(r'^(?:№|N[oо°º2]|М[оеo]|Ne|Nе|N)\.?$')
34
35_CYRILLIC_LANGS = {'ukr', 'rus', 'bel', 'bul', 'srp', 'mkd'}
36
37_LATIN_LANGS = {'eng', 'deu', 'fra', 'spa', 'ita', 'por', 'pol', 'nld', 'ces'}
38
39_wordlists: dict[str, set[str]] = {}
40
41
42
43def _tesseract(img: Image.Image, langs: str, psm: int, extra: str = '') -> str:
44 try:
45 return pytesseract.image_to_string(img, lang=langs, config=f'--psm {psm} {extra}'.strip())
46 except pytesseract.TesseractError as e:
47 raise ConversionError(f'OCR failed: {e}') from e
48
49
50def _tesseract_data(img: Image.Image, langs: str) -> dict:
51 try:
52 return pytesseract.image_to_data(img, lang=langs, config='--psm 3', output_type=pytesseract.Output.DICT)
53 except pytesseract.TesseractError as e:
54 raise ConversionError(f'OCR failed: {e}') from e
55
56
57def _find_borderless(d: dict) -> list[tuple[list[int], list[int]]]:
58 words = [(d['left'][i], d['top'][i], d['left'][i] + d['width'][i], d['top'][i] + d['height'][i])
59 for i, t in enumerate(d['text'])
60 if d['level'][i] == 5 and re.search(r'\w', t or '') and d['height'][i] > 5]
61 if len(words) < BL_MIN_ROWS * BL_MIN_COLS:
62 return []
63 hmed = statistics.median(w[3] - w[1] for w in words)
64 rows = []
65 for w in sorted(words, key=lambda w: (w[1] + w[3]) / 2):
66 yc = (w[1] + w[3]) / 2
67 if rows and abs(yc - rows[-1][0] / rows[-1][1]) < 0.6 * hmed:
68 rows[-1][0] += yc
69 rows[-1][1] += 1
70 rows[-1][2].append(w)
71 else:
72 rows.append([yc, 1, [w]])
73 gap = 0.9 * hmed
74 lines = []
75 for _, _, ws in rows:
76 ws.sort()
77 segs = [[ws[0][0], ws[0][2]]]
78 for w in ws[1:]:
79 if w[0] - segs[-1][1] > gap:
80 segs.append([w[0], w[2]])
81 else:
82 segs[-1][1] = max(segs[-1][1], w[2])
83 lines.append((min(w[1] for w in ws), max(w[3] for w in ws), segs))
84 tables, run = [], []
85 for ln in lines + [None]:
86 if ln is not None and len(ln[2]) >= BL_MIN_COLS and (not run or ln[0] - run[-1][1] < 2.5 * hmed):
87 run.append(ln)
88 continue
89 if len(run) >= BL_MIN_ROWS:
90 tables.append(run)
91 run = [ln] if ln is not None and len(ln[2]) >= BL_MIN_COLS else []
92 grids = []
93 for run in tables:
94 spans = sorted([a, b] for _, _, segs in run for a, b in segs)
95 cols = [spans[0]]
96 for a, b in spans[1:]:
97 if a - cols[-1][1] > 0.5 * hmed:
98 cols.append([a, b])
99 else:
100 cols[-1][1] = max(cols[-1][1], b)
101 if len(cols) < BL_MIN_COLS:
102 continue
103 pad = int(0.3 * hmed)
104 xs = [cols[0][0] - pad] + [(a[1] + b[0]) // 2 for a, b in zip(cols, cols[1:])] + [cols[-1][1] + pad]
105 ys = ([run[0][0] - pad] + [(a[1] + b[0]) // 2 for a, b in zip(run, run[1:])] + [run[-1][1] + pad])
106 grids.append((ys, xs))
107 return grids
108
109
110def _has_rule(img: Image.Image) -> bool:
111 """A long horizontal dark run (any table rule; on a page skewed by up to ~3 deg it is still >= w/12)."""
112 small = np.asarray(img.resize((max(1, img.width // 2), max(1, img.height // 2)), Image.BILINEAR)) < GRID_DARK
113 wide = small | np.roll(small, 1, axis=1) | np.roll(small, -1, axis=1)
114 return bool(_runs(wide, max(40, small.shape[1] // 24)).any())
115
116
117def _deskew(img: Image.Image) -> Image.Image:
118 """Rotate by the angle (-3..3 deg, step 0.1) that makes text lines sharpest in the row profile."""
119 small = img.resize((max(1, img.width // 4), max(1, img.height // 4)), Image.BILINEAR)
120 best_angle, best_score = 0.0, -1.0
121 for tenth in range(-30, 31):
122 a = tenth / 10
123 ink = np.asarray(small.rotate(a, resample=Image.BILINEAR, fillcolor=255)) < GRID_DARK
124 prof = ink.sum(axis=1).astype(np.float64)
125 score = float(((prof[1:] - prof[:-1]) ** 2).sum())
126 if score > best_score:
127 best_angle, best_score = a, score
128 if abs(best_angle) < 0.15:
129 return img
130 straight = img.rotate(best_angle, resample=Image.BICUBIC, fillcolor=255)
131 straight.info['deskew_angle'] = best_angle
132 return straight
133
134
135def _runs(mask: np.ndarray, length: int) -> np.ndarray:
136 """Per row of a boolean mask: True where a run of >= length True values ends (window sum test)."""
137 cs = np.cumsum(mask, axis=1, dtype=np.int32)
138 cs = np.concatenate([np.zeros((mask.shape[0], 1), np.int32), cs], axis=1)
139 return (cs[:, length:] - cs[:, :-length]) >= length
140
141
142def _segments(idx: np.ndarray, gap: int = 2) -> list[tuple[int, int]]:
143 """Sorted indices -> (first, last) groups of neighbours."""
144 out = []
145 for i in idx.tolist():
146 if out and i - out[-1][1] <= gap:
147 out[-1] = (out[-1][0], i)
148 else:
149 out.append((i, i))
150 return out
151
152
153def _find_grids(img: Image.Image) -> list[tuple[list[int], list[int]]]:
154 """Ruled tables as (row line y's, column line x's), top to bottom. Empty when there is no full grid."""
155 ink = np.asarray(img) < GRID_DARK
156 h, w = ink.shape
157 wide, tall = ink.copy(), ink.copy()
158 for d in (1, 2):
159 wide |= np.roll(ink, d, axis=1) | np.roll(ink, -d, axis=1)
160 tall |= np.roll(ink, d, axis=0) | np.roll(ink, -d, axis=0)
161 min_h = max(80, w // 12)
162 hrun = _runs(wide, min_h)
163 hlines = []
164 for y0, y1 in _segments(np.flatnonzero(hrun.any(axis=1))):
165 if y1 - y0 > 12:
166 continue
167 xs = np.flatnonzero(hrun[y0:y1 + 1].any(axis=0))
168 hlines.append(((y0 + y1) // 2, int(xs.min()), int(xs.max()) + min_h))
169 grids, used = [], set()
170 for i in sorted(range(len(hlines)), key=lambda k: hlines[k][1] - hlines[k][2]):
171 if i in used:
172 continue
173 y, x0, x1 = hlines[i]
174
175 group = [j for j, (yy, a, b) in enumerate(hlines)
176 if j not in used and a >= x0 - 15 and b <= x1 + 15 and b - a >= 0.6 * (x1 - x0)]
177 rows = sorted(hlines[j][0] for j in group)
178 if len(rows) < GRID_MIN_ROWS + 1:
179 continue
180 top, bottom = rows[0], rows[-1]
181
182 left = max(0, x0 - 15)
183 box = tall[top + 3:bottom - 2, left:min(w, x1 + 15)]
184 if box.shape[0] < 10:
185 continue
186 full = np.flatnonzero(box.mean(axis=0) >= 0.9)
187 cols = [left + (c0 + c1) // 2 for c0, c1 in _segments(full) if c1 - c0 <= 12]
188 if len(cols) < GRID_MIN_COLS + 1 or cols[0] > x0 + 15 or cols[-1] < x1 - 15:
189 continue
190 used.update(group)
191 grids.append((rows, cols))
192 return sorted(grids, key=lambda g: g[0][0])
193
194
195def _to_straight(data: dict, img: Image.Image, straight: Image.Image) -> dict:
196 """Words read on the page as scanned, with boxes moved to where they are on the straightened page: text
197 outside tables keeps Tesseract's own reading (straightening resamples the image and can change a comma)."""
198 angle = straight.info.get('deskew_angle', 0.0) if straight is not img else 0.0
199 if not angle:
200 return data
201 a = np.radians(angle)
202 cx, cy = img.width / 2, img.height / 2
203 out = dict(data)
204 out['left'], out['top'] = [], []
205 for x, y, w, h in zip(data['left'], data['top'], data['width'], data['height']):
206 xc, yc = x + w / 2 - cx, y + h / 2 - cy
207 nx, ny = cx + xc * np.cos(a) + yc * np.sin(a), cy - xc * np.sin(a) + yc * np.cos(a)
208 out['left'].append(int(nx - w / 2))
209 out['top'].append(int(ny - h / 2))
210 return out
211
212
213def _read_sheet(cells: list[Image.Image], langs: str) -> list[tuple[str, bool]]:
214 """Cells in one Tesseract call: a sheet of cells one under another (a call per cell is ~30 times slower).
215 Per cell: its text and whether it looks misread (stray marks, a lone letter, letters in a number)."""
216 pads = [ImageOps.expand(c, border=20, fill=255) for c in cells]
217 sheet = Image.new('L', (max(p.width for p in pads), sum(p.height + 30 for p in pads)), 255)
218 spans, y = [], 0
219 for p in pads:
220 sheet.paste(p, (0, y))
221 spans.append((y, y + p.height))
222 y += p.height + 30
223 try:
224 d = pytesseract.image_to_data(sheet, lang=langs, config='--psm 6 -c preserve_interword_spaces=1',
225 output_type=pytesseract.Output.DICT)
226 except pytesseract.TesseractError as e:
227 raise ConversionError(f'OCR failed: {e}') from e
228 words = [[] for _ in cells]
229 for i, t in enumerate(d['text']):
230 if d['level'][i] != 5 or not t.strip():
231 continue
232 yc = d['top'][i] + d['height'][i] / 2
233 k = next((n for n, (a, b) in enumerate(spans) if a <= yc < b), None)
234 if k is not None:
235 words[k].append((d['left'][i], t.strip()))
236 out = []
237 for ws in words:
238 ws.sort()
239 kept = [t for _, t in ws if re.search(r'[^\W_]', t)]
240 text = ' '.join(kept).strip(' |_:;`\'"(')
241 bad = (len(kept) != len(ws) or (len(text) == 1 and not text.isdigit())
242 or bool(re.search(r'\d', text) and re.search(r'[^\d\s.,\-]', text)
243 and not re.search(r'[^\W\d_]{2}', text))
244 or bool(re.search(r'\d[.,;:]$|^[^\w-]|^\d{4,}(?:[.,]\d+)?$', text)))
245 out.append((text, bad))
246 return out
247
248
249def _read_table(crops, langs: str) -> list[list[str]]:
250 """All cells in one call; cells that look misread are read again in one call with scan specks filtered
251 out, and only those still in doubt one by one."""
252 flat = [c for row in crops for c in row]
253 first = _read_sheet(flat, langs)
254 texts = [t for t, _ in first]
255 doubt = [k for k, (_, bad) in enumerate(first) if bad]
256 if doubt:
257 again = _read_sheet([flat[k].filter(ImageFilter.MedianFilter(3)) for k in doubt], langs)
258 still = []
259 for k, (text, bad) in zip(doubt, again):
260 old = texts[k]
261 same = re.sub(r'\s', '', text) == re.sub(r'\s', '', old)
262 if text and (not bad or (same and text.count(' ') > old.count(' '))):
263 texts[k] = text
264 else:
265 still.append(k)
266 for k in still[:6]:
267 texts[k] = _read_cell(flat[k], langs) or texts[k]
268 n = len(crops[0])
269 table = [texts[r * n:(r + 1) * n] for r in range(len(crops))]
270 _even_thousands(table, crops, langs)
271 for r, row in enumerate(table):
272 for c, cell in enumerate(row):
273 row[c] = _gap_thousands(crops[r][c], cell)
274 _cyrillic_cells(table, crops, langs)
275 return table
276
277
278def _read_cell(cell: Image.Image, langs: str) -> str:
279 """A cell as one text line. Scan specks read as stray marks ('З -'): read again with specks filtered out
280 (not always: the filter can close the thousands gap in '2 500')."""
281 def read(im):
282 raw = _tesseract(ImageOps.expand(im, border=20, fill=255), langs, 7, '-c preserve_interword_spaces=1')
283 return re.sub(r'\s+', ' ', raw).strip(), _clean_cell(raw)
284 raw, text = read(cell)
285 if raw != text or (len(text) == 1 and not text.isdigit()):
286 _, again = read(cell.filter(ImageFilter.MedianFilter(3)))
287 if again and re.sub(r'\s', '', again) != re.sub(r'\s', '', text):
288 return again
289 if again and again.count(' ') > text.count(' '):
290 return again
291 return text
292
293
294def _cyrillic_cells(table, crops, langs: str) -> None:
295 """With Latin and Cyrillic languages together, a short cell of a Cyrillic table is often read as Latin
296 ('шт.' -> 'LUT.', 'М500' -> 'M500'). Such a cell is read again with the Cyrillic languages only and the new
297 reading is kept when its words are words of those languages."""
298 parts = langs.split('+')
299 cyr = [x for x in parts if x in _CYRILLIC_LANGS]
300 if not cyr or not set(parts) & _LATIN_LANGS:
301 return
302 text = ' '.join(c for r in table for c in r)
303 n_cyr, n_lat = len(re.findall(r'[\u0400-\u04ff]', text)), len(re.findall(r'[A-Za-z]', text))
304 if n_cyr < 1.5 * n_lat:
305 return
306 words = [_wordlist(x) for x in cyr]
307 latin = [(r, c) for r, row in enumerate(table) for c, cell in enumerate(row) if re.search(r'[A-Za-z]', cell)]
308 if not latin:
309 return
310 for (r, c), (again, _) in zip(latin, _read_sheet([crops[r][c] for r, c in latin], '+'.join(cyr))):
311 letters = [re.sub(r'[^\w]|\d|_', '', w).lower() for w in again.split()]
312 if again and not re.search(r'[A-Za-z]', again) and all(
313 not w or any(w in d for d in words) for w in letters):
314 table[r][c] = again
315
316
317def _clean_cell(text: str) -> str:
318 """One cell read as a line: parts after a wide gap that hold no letter or digit are scan specks."""
319 parts = [p for p in re.split(r'\s{3,}', text.strip()) if re.search(r'\w', p)]
320 tokens = re.sub(r'\s+', ' ', ' '.join(parts)).split()
321 while tokens and not re.search(r'\w', tokens[0]):
322 tokens.pop(0)
323 while tokens and not re.search(r'\w', tokens[-1]):
324 tokens.pop()
325 return ' '.join(tokens).strip(' |_:;`\'"(')
326
327
328def _fix_columns(table: list[list[str]]) -> list[list[str]]:
329 """In a column of numbers, letters that look like digits are digits ('З' -> '3'); its header read as
330 'Мо' / 'No' is the number sign '№'."""
331 if len(table) < 3:
332 return table
333 width = max(len(r) for r in table)
334 for c in range(width):
335 cells = [r[c] for r in table[1:] if c < len(r) and r[c]]
336 numeric = [x for x in cells if re.fullmatch(r'[\d\s.,\-]+', x)]
337 if not cells or len(numeric) * 2 < len(cells):
338 continue
339 for r in table[1:]:
340 if c < len(r) and r[c]:
341 r[c] = re.sub(r'^[^\w\-]+|[^\w]+$', '', r[c]) or r[c]
342 if c < len(r) and r[c] and r[c] not in numeric:
343 fixed = r[c].translate(_DIGIT_LOOKALIKE)
344 if re.fullmatch(r'[\d\s.,\-]+', fixed) and re.search(r'\d', r[c]):
345 r[c] = fixed
346 elif re.fullmatch(r'[\d\s.,\-]+', fixed) and len(r[c]) <= 2:
347 r[c] = fixed
348 if c < len(table[0]) and _NUMERO.match(table[0][c]) and all(re.fullmatch(r'\d+', x) for x in
349 (r[c] for r in table[1:] if c < len(r) and r[c])):
350 table[0][c] = '№'
351 return table
352
353
354def table_to_markdown(rows) -> str:
355 width = max(len(r) for r in rows)
356 clean = [[_cell(c) for c in list(r) + [''] * (width - len(r))] for r in rows]
357 lines = ['| ' + ' | '.join(clean[0]) + ' |', '| ' + ' | '.join(['---'] * width) + ' |']
358 lines += ['| ' + ' | '.join(r) + ' |' for r in clean[1:]]
359 return '\n'.join(lines)
360
361
362def _cell(c) -> str:
363 return re.sub(r'\s+', ' ', str(c or '')).replace('|', '\\|').strip()
364
365
366def _wordlist(lang: str) -> set[str]:
367 """Words of Tesseract's dictionary for a language (lower case), read once from its traineddata."""
368 if lang in _wordlists:
369 return _wordlists[lang]
370 words: set[str] = set()
371 try:
372 tessdata = os.environ.get('TESSDATA_PREFIX') or _tessdata_dir()
373 src = os.path.join(tessdata, f'{lang}.traineddata')
374 with tempfile.TemporaryDirectory() as tmp:
375 base = os.path.join(tmp, lang)
376 subprocess.run(['combine_tessdata', '-e', src, base + '.lstm-word-dawg', base + '.lstm-unicharset'],
377 capture_output=True, timeout=60, check=True)
378 subprocess.run(['dawg2wordlist', base + '.lstm-unicharset', base + '.lstm-word-dawg', base + '.txt'],
379 capture_output=True, timeout=120, check=True)
380 with open(base + '.txt', encoding='utf-8') as f:
381 words = {w.strip().lower() for w in f if w.strip()}
382 except Exception:
383 words = set()
384 _wordlists[lang] = words
385 return words
386
387
388def _tessdata_dir() -> str:
389 out = subprocess.run(['tesseract', '--list-langs'], capture_output=True, text=True, timeout=30)
390 m = re.search(r'"([^"]+)"', out.stdout + out.stderr)
391 return m.group(1) if m else '/usr/share/tesseract-ocr/5/tessdata'
392
393
394_GROUPED = re.compile(r'\d{1,3}(?:([ .,])\d{3})+(?:([.,])\d+)?')
395
396
397def _even_thousands(table, crops, langs: str) -> None:
398 """In a column where numbers group thousands with a space ('74 160,00'), a number grouped with a dot
399 ('40.530,00') is most likely a misread gap: read again, and when the digits stay the same, group it like
400 the rest of the column. A column that really uses dots is left alone."""
401 for c in range(len(table[0])):
402 styles = {}
403 for r in range(1, len(table)):
404 m = _GROUPED.fullmatch(table[r][c]) if c < len(table[r]) else None
405 if m:
406 styles[r] = (m.group(1), m.group(2))
407 if len(styles) < 3:
408 continue
409 seps = [g for g, _ in styles.values()]
410 main = max(set(seps), key=seps.count)
411 if main != ' ' or seps.count(main) * 2 <= len(seps):
412 continue
413 for r, (g, dec) in styles.items():
414 if g == main or g == dec:
415 continue
416 old = table[r][c]
417 again = _read_cell(crops[r][c].filter(ImageFilter.MedianFilter(3)), langs)
418 same = re.sub(r'\D', '', again) == re.sub(r'\D', '', old)
419 if same and _GROUPED.fullmatch(again) and _GROUPED.fullmatch(again).group(1) == main:
420 table[r][c] = again
421 else:
422 head, _, tail = old.rpartition(dec) if dec else (old, '', '')
423 table[r][c] = head.replace(g, main) + (dec + tail if dec else '')
424
425
426def _gap_thousands(cell: Image.Image, text: str) -> str:
427 """'2500' where the image shows '2 500': Tesseract can drop a narrow thousands gap. The glyphs are measured:
428 when every thousands boundary is a gap at least twice as wide as the gaps between the other characters,
429 the spaces go back. Anything that does not split into exactly one glyph per character stays as read."""
430 m = re.fullmatch(r'(\d{4,})([.,]\d+)?', text)
431 if not m:
432 return text
433 ink = (np.asarray(cell.filter(ImageFilter.MedianFilter(3))) < 140).any(axis=0)
434 runs, x = [], 0
435 while x < len(ink):
436 if ink[x]:
437 start = x
438 while x < len(ink) and ink[x]:
439 x += 1
440 runs.append((start, x))
441 else:
442 x += 1
443 if len(runs) != len(text):
444 return text
445 gaps = [b[0] - a[1] for a, b in zip(runs, runs[1:])]
446 n = len(m.group(1))
447 marks = [i for i in range(1, n) if (n - i) % 3 == 0]
448 others = [g for i, g in enumerate(gaps, 1) if i not in marks]
449 if not others:
450 return text
451 usual = statistics.median(others)
452 if all(gaps[i - 1] >= max(2 * usual, usual + 6) for i in marks):
453 digits = m.group(1)
454 grouped = ''.join((' ' if i in marks else '') + ch for i, ch in enumerate(digits))
455 return grouped + (m.group(2) or '')
456 return text