ocr-foundry 0.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,238 @@
1
+ """Deterministic page affine geometry, separate from line augmentation.
2
+
3
+ Coordinates use continuous pixel edges; pixel (i, j) has center (i+.5, j+.5).
4
+ Only numerical errors within 1e-9 pixels of an integer are snapped. OpenCV's
5
+ integer-center convention is handled only at the rasterization boundary.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import math
11
+ from dataclasses import dataclass
12
+ from typing import Any
13
+
14
+ import cv2
15
+ import numpy as np
16
+
17
+ from .errors import InputValidationError
18
+
19
+ _SNAP_TOLERANCE = 1e-9
20
+ # Bound memory and respect warpAffine's SHRT_MAX dimension restriction.
21
+ _MAX_DIMENSION = 32766
22
+ _MAX_PIXELS = 64_000_000
23
+
24
+
25
+ def _transform_regions(lines: list[dict[str, Any]], tables: list[dict[str, Any]] | None, mapper: Any) -> None:
26
+ regions = [word for line in lines for word in line.get("words", [])]
27
+ for table in tables or []:
28
+ regions.append(table)
29
+ regions.extend(table["cells"])
30
+ for region in regions:
31
+ polygon = mapper(region["polygon"])
32
+ bounds = np.asarray(polygon)
33
+ low, high = np.floor(bounds.min(axis=0)).astype(int), np.ceil(bounds.max(axis=0)).astype(int)
34
+ region["polygon"] = polygon
35
+ region["box"] = {"x": int(low[0]), "y": int(low[1]),
36
+ "w": int(high[0]-low[0]), "h": int(high[1]-low[1])}
37
+
38
+
39
+ def _snap(values: np.ndarray) -> np.ndarray:
40
+ nearest = np.rint(values)
41
+ return np.where(np.abs(values - nearest) <= _SNAP_TOLERANCE, nearest, values)
42
+
43
+
44
+ def _size(width: int, height: int) -> tuple[int, int]:
45
+ if not (1 <= width <= _MAX_DIMENSION and 1 <= height <= _MAX_DIMENSION):
46
+ raise InputValidationError(
47
+ f"page transform dimensions must be between 1 and {_MAX_DIMENSION} pixels"
48
+ )
49
+ if width * height > _MAX_PIXELS:
50
+ raise InputValidationError(f"page transform exceeds {_MAX_PIXELS} pixels")
51
+ return width, height
52
+
53
+
54
+ def _translation(x: float, y: float) -> np.ndarray:
55
+ return np.array([[1, 0, x], [0, 1, y], [0, 0, 1]], dtype=np.float64)
56
+
57
+
58
+ def _corners(x: float, y: float, w: float, h: float) -> list[list[float]]:
59
+ return [[x, y], [x + w, y], [x + w, y + h], [x, y + h]]
60
+
61
+
62
+ def _points(matrix: np.ndarray, points: list[list[float]]) -> np.ndarray:
63
+ array = np.asarray(points, dtype=np.float64)
64
+ result = array @ matrix[:2, :2].T + matrix[:2, 2]
65
+ if not np.isfinite(result).all():
66
+ raise InputValidationError("page transform produced non-finite annotation coordinates")
67
+ return _snap(result)
68
+
69
+
70
+ @dataclass(frozen=True)
71
+ class PageTransform:
72
+ """One source-to-output matrix and its pre-crop rasterization plan."""
73
+
74
+ matrix: np.ndarray
75
+ expanded_matrix: np.ndarray
76
+ source_size: tuple[int, int]
77
+ expanded_size: tuple[int, int]
78
+ output_size: tuple[int, int]
79
+ crop: tuple[int, int, int, int] | None
80
+ operations: list[dict[str, Any]]
81
+ flip: str = "none"
82
+ def provenance(self) -> dict[str, Any]:
83
+ return {
84
+ "contract_version": 1,
85
+ "coordinate_convention": "continuous_pixel_edges; centers=(i+0.5,j+0.5); x_right,y_down",
86
+ "matrix": self.matrix.tolist(),
87
+ "source_size": list(self.source_size),
88
+ "output_size": list(self.output_size),
89
+ "operations": self.operations,
90
+ "interpolation": "linear",
91
+ "border": {"mode": "constant", "value": 255},
92
+ }
93
+
94
+ def points(self, points: list[list[float]]) -> list[list[float]]:
95
+ """Map and validate geometry, allowing only numerical snapping at bounds."""
96
+ result = _points(self.matrix, points)
97
+ width, height = self.output_size
98
+ if (result < 0).any() or (result > [width, height]).any():
99
+ raise InputValidationError(
100
+ "page crop would remove line canvas or annotation geometry; "
101
+ "the complete line canvas including padding must survive"
102
+ )
103
+ return result.tolist()
104
+
105
+ def annotations(self, lines: list[dict[str, Any]], spans: list[dict[str, Any]],
106
+ tables: list[dict[str, Any]] | None = None) -> None:
107
+ """Move existing logical lines and matching one-per-line hierarchy spans."""
108
+ for line, span in zip(lines, spans, strict=True):
109
+ box = line["box"]
110
+ polygon = self.points(_corners(box["x"], box["y"], box["w"], box["h"]))
111
+ bounds = np.asarray(polygon)
112
+ low = np.floor(bounds.min(axis=0)).astype(int)
113
+ high = np.ceil(bounds.max(axis=0)).astype(int)
114
+ line["box"] = {
115
+ "x": int(low[0]),
116
+ "y": int(low[1]),
117
+ "w": int(high[0] - low[0]),
118
+ "h": int(high[1] - low[1]),
119
+ }
120
+ line["canvas_polygon"] = polygon
121
+ if "polygon" in line:
122
+ line["polygon"] = self.points(line["polygon"])
123
+ if "baseline" in line:
124
+ line["baseline"]["points"] = self.points(line["baseline"]["points"])
125
+ span["box"] = line["box"].copy()
126
+ span["canvas_polygon"] = [point.copy() for point in polygon]
127
+ _transform_regions(lines, tables, self.points)
128
+
129
+ def raster(self, canvas: np.ndarray) -> np.ndarray:
130
+ """Resample scale/rotation once, then crop without resampling or ink loss."""
131
+ if np.array_equal(self.expanded_matrix, np.eye(3)):
132
+ expanded = canvas
133
+ else:
134
+ cv_matrix = _translation(-0.5, -0.5) @ self.expanded_matrix @ _translation(0.5, 0.5)
135
+ expanded = cv2.warpAffine(
136
+ canvas,
137
+ cv_matrix[:2],
138
+ self.expanded_size,
139
+ flags=cv2.INTER_LINEAR,
140
+ borderMode=cv2.BORDER_CONSTANT,
141
+ borderValue=255 if canvas.ndim == 2 else (255, 255, 255),
142
+ )
143
+ if self.crop is not None:
144
+ x, y, w, h = self.crop
145
+ # Check every channel, including antialiased fringes outside canvas bounds.
146
+ if any(
147
+ np.any(part != 255)
148
+ for part in (
149
+ expanded[:y],
150
+ expanded[y + h :],
151
+ expanded[y : y + h, :x],
152
+ expanded[y : y + h, x + w :],
153
+ )
154
+ ):
155
+ raise InputValidationError("page crop would remove nonwhite raster pixels")
156
+ cropped = expanded[y : y + h, x : x + w].copy()
157
+ else:
158
+ cropped = expanded
159
+
160
+ if self.flip == "horizontal":
161
+ return cv2.flip(cropped, 1)
162
+ if self.flip == "vertical":
163
+ return cv2.flip(cropped, 0)
164
+ if self.flip == "both":
165
+ return cv2.flip(cropped, -1)
166
+ return cropped
167
+
168
+
169
+ def plan_page_transform(
170
+ width: int,
171
+ height: int,
172
+ scale: float,
173
+ rotation: float,
174
+ crop: tuple[int, int, int, int] | None,
175
+ flip: str = "none",
176
+ ) -> PageTransform:
177
+ """Validate fixed parameters and plan resize -> expanded CCW rotation -> crop -> flip."""
178
+ if not math.isfinite(scale) or scale <= 0:
179
+ raise InputValidationError("page scale must be a positive finite number")
180
+ if not math.isfinite(rotation):
181
+ raise InputValidationError("page rotation must be finite")
182
+ _size(width, height)
183
+ scaled = [width * scale, height * scale]
184
+ if not all(math.isfinite(value) and value <= _MAX_DIMENSION + 0.5 for value in scaled):
185
+ raise InputValidationError("page scale produces impossible dimensions")
186
+ sw, sh = _size(round(scaled[0]), round(scaled[1]))
187
+ resize = np.diag([sw / width, sh / height, 1.0])
188
+ # Signed remainder retains tiny negative angles that % 360 can round to 360.
189
+ angle = math.remainder(rotation, 360)
190
+ if angle % 90 == 0:
191
+ # Exact cardinal coefficients avoid trig roundoff without erasing small
192
+ # but intentional rotations near a cardinal angle.
193
+ cos, sin = ((1, 0), (0, 1), (-1, 0), (0, -1))[int(angle // 90) % 4]
194
+ else:
195
+ radians = math.radians(angle)
196
+ cos, sin = math.cos(radians), math.sin(radians)
197
+ # In y-down coordinates positive angles move rightward points upward (CCW).
198
+ rotate = np.array([[cos, sin, 0], [-sin, cos, 0], [0, 0, 1]], dtype=np.float64)
199
+ rotate = _translation(sw / 2, sh / 2) @ rotate @ _translation(-sw / 2, -sh / 2)
200
+ corners = _points(rotate, _corners(0, 0, sw, sh))
201
+ low, high = corners.min(axis=0), corners.max(axis=0)
202
+ extent = _snap(high - low)
203
+ ew, eh = _size(math.ceil(extent[0]), math.ceil(extent[1]))
204
+ expanded_matrix = _translation(-low[0], -low[1]) @ rotate @ resize
205
+ matrix = expanded_matrix
206
+ output_size = (ew, eh)
207
+ operations: list[dict[str, Any]] = [
208
+ {
209
+ "operation": "resize",
210
+ "scale": scale,
211
+ "size": [sw, sh],
212
+ "actual_scale": [sw / width, sh / height],
213
+ },
214
+ {"operation": "rotate", "degrees": rotation, "expanded_size": [ew, eh]},
215
+ ]
216
+ if crop is not None:
217
+ if len(crop) != 4 or any(type(value) is not int for value in crop):
218
+ raise InputValidationError("page crop must be an integer rectangle X Y W H")
219
+ x, y, w, h = crop
220
+ if x < 0 or y < 0 or w <= 0 or h <= 0 or x + w > ew or y + h > eh:
221
+ raise InputValidationError("page crop must be positive and inside the expanded page")
222
+ matrix = _translation(-x, -y) @ matrix
223
+ output_size = (w, h)
224
+ operations.append({"operation": "crop", "rectangle": list(crop)})
225
+ if flip not in {"none", "horizontal", "vertical", "both"}:
226
+ raise InputValidationError(f"invalid flip mode {flip!r}; must be 'none', 'horizontal', 'vertical', or 'both'")
227
+ if flip != "none":
228
+ ow, oh = output_size
229
+ sx = -1.0 if flip in {"horizontal", "both"} else 1.0
230
+ sy = -1.0 if flip in {"vertical", "both"} else 1.0
231
+ tx = float(ow) if flip in {"horizontal", "both"} else 0.0
232
+ ty = float(oh) if flip in {"vertical", "both"} else 0.0
233
+ flip_mat = np.array([[sx, 0.0, tx], [0.0, sy, ty], [0.0, 0.0, 1.0]], dtype=np.float64)
234
+ matrix = flip_mat @ matrix
235
+ operations.append({"operation": "flip", "mode": flip})
236
+ return PageTransform(
237
+ matrix, expanded_matrix, (width, height), (ew, eh), output_size, crop, operations, flip
238
+ )