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.
khocr_gen/rendering.py ADDED
@@ -0,0 +1,1607 @@
1
+ """ImageRenderer - synthetic text-to-image rendering with isolated augmentation.
2
+
3
+ Core design: each text line is rendered to a clean canvas (no augmentation),
4
+ then for each enabled augmentation method a copy of the clean canvas is produced with exactly one augmentation effect applied.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import random
10
+ from dataclasses import dataclass, field
11
+ from pathlib import Path
12
+ from typing import TYPE_CHECKING, Any
13
+
14
+ import cv2
15
+ import numpy as np
16
+ from PIL import Image, ImageDraw, ImageFilter
17
+
18
+ from . import _rust_accel as _ra
19
+ from .augmentation import (
20
+ _RGB_PREFERRED_METHODS,
21
+ _RUST_ACCEL_FUNCTIONS,
22
+ AUG_METHODS,
23
+ PYTHON_AUG_METHODS,
24
+ TEXT_HEIGHT_GUARDED_METHODS,
25
+ scale_intensity_for_script,
26
+ )
27
+ from .config import TEXT_EFFECT_NAMES
28
+ from .errors import InputValidationError
29
+ from .line_height import sample_font_scale, sample_line_height, sample_vertical_padding_ratio
30
+ from .logging import get_logger
31
+ from .text_support import (
32
+ check_cluster_fallback_coverage,
33
+ coverage_error,
34
+ detect_script,
35
+ find_fallback_fonts_for_clusters,
36
+ invalid_control,
37
+ needs_glyph,
38
+ resolve_bidi_runs,
39
+ split_grapheme_clusters,
40
+ )
41
+
42
+ if TYPE_CHECKING:
43
+ from .config import AugMethodConfig, GenerationConfig, TextEffectConfig
44
+ from .fonts import FontManager
45
+
46
+ HAS_PIL = True # Import of PIL.Image above verifies this
47
+
48
+ _LOGGER = get_logger("rendering")
49
+
50
+ # Text colors guaranteed to contrast with the sampled backgrounds.
51
+ _DECO_DARK_TEXT_COLORS = [
52
+ (192, 57, 43), # red
53
+ (31, 97, 141), # blue
54
+ (30, 132, 73), # green
55
+ (108, 52, 131), # purple
56
+ (185, 119, 14), # orange
57
+ (136, 78, 160), # magenta
58
+ ]
59
+ _DECO_LIGHT_TEXT_COLORS = [
60
+ (255, 214, 100),
61
+ (130, 224, 255),
62
+ (180, 255, 180),
63
+ (255, 160, 160),
64
+ (255, 200, 255),
65
+ (255, 245, 160),
66
+ ]
67
+
68
+ # Bright, saturated colors for the "neon" text effect (RGB mode only).
69
+ _NEON_COLORS_RGB = [
70
+ (255, 0, 180),
71
+ (0, 255, 255),
72
+ (57, 255, 20),
73
+ (255, 255, 0),
74
+ (255, 60, 0),
75
+ (180, 0, 255),
76
+ ]
77
+
78
+ # Effects that draw an offset/blurred halo behind the glyphs via a rasterized
79
+ # alpha mask (shadow, echo, glow, neon all share the same mask-composite path).
80
+ _MASK_EFFECTS: frozenset[str] = frozenset({"shadow", "echo", "glow", "neon", "glitch", "pixel"})
81
+ # Effects that resize the font instead of changing how glyphs are drawn.
82
+ _SIZE_EFFECTS: frozenset[str] = frozenset({"huge", "tiny"})
83
+
84
+
85
+ class _BoundedCache(dict):
86
+ """Dict that evicts the oldest entries (FIFO) when maxsize is exceeded."""
87
+
88
+ def __init__(self, maxsize: int) -> None:
89
+ super().__init__()
90
+ self._maxsize = maxsize
91
+ self._keys: list[Any] = []
92
+
93
+ def __setitem__(self, key: Any, value: Any) -> None:
94
+ if key not in self:
95
+ if len(self) >= self._maxsize:
96
+ evict = max(1, self._maxsize // 10)
97
+ for _ in range(evict):
98
+ if self._keys:
99
+ oldest = self._keys.pop(0)
100
+ super().pop(oldest, None)
101
+ self._keys.append(key)
102
+ super().__setitem__(key, value)
103
+
104
+
105
+ @dataclass
106
+ class DecorStyle:
107
+ """Per-line decoration state sampled before rendering."""
108
+
109
+ bold: bool = False
110
+ italic: bool = False
111
+ underline: bool = False
112
+ color: bool = False # request a single random line color (RGB mode only)
113
+ sub_indices: list[int] = field(default_factory=list)
114
+ super_indices: list[int] = field(default_factory=list)
115
+ effect: str | None = None # one of TEXT_EFFECT_NAMES, or None
116
+
117
+ @property
118
+ def active(self) -> bool:
119
+ return (
120
+ self.bold
121
+ or self.italic
122
+ or self.underline
123
+ or self.color
124
+ or bool(self.sub_indices)
125
+ or bool(self.super_indices)
126
+ or self.effect is not None
127
+ )
128
+
129
+
130
+ class ImageRenderer:
131
+ """Render text to images with isolated augmentation.
132
+
133
+ Each enabled augmentation method receives a copy of the clean rendered canvas and applies exactly one effect;
134
+ no stacked/combined augmentations.
135
+ """
136
+
137
+ def __init__(self, font_manager: FontManager, cfg: GenerationConfig) -> None:
138
+ self._cfg = cfg
139
+ self.font_manager = font_manager
140
+ if cfg.font_intensity_scales:
141
+ paths = {str(Path(entry[0]).resolve()) for entry in font_manager.all_fonts}
142
+ for key in cfg.font_intensity_scales:
143
+ if Path(key).name == key and sum(Path(path).name == key for path in paths) > 1:
144
+ raise InputValidationError(
145
+ f"Ambiguous font intensity key {key!r}; specify an exact font path",
146
+ code="ambiguous_font_scale",
147
+ )
148
+ self.image_height = cfg.image_height
149
+ self.image_width = cfg.image_width
150
+ self.color_mode = int(cfg.color_mode)
151
+ self.random_align_when_padded = bool(cfg.random_align_when_padded)
152
+ self.mixed_font_prob = float(max(0.0, min(1.0, cfg.mixed_font_prob)))
153
+ self.font_size_mode = getattr(cfg, "font_size_mode", "fixed")
154
+ self.vertical_padding_mode = getattr(cfg, "vertical_padding_mode", "fixed")
155
+
156
+ # Derived properties
157
+ self._pil_mode: str = "L" if self.color_mode == 1 else "RGB"
158
+ self._bg_color_mode: str = getattr(cfg, "bg_color_mode", "random")
159
+
160
+ # Caches
161
+ self._font_ref_cache: _BoundedCache = _BoundedCache(maxsize=1_000)
162
+ self._glyph_support_cache: _BoundedCache = _BoundedCache(maxsize=50_000)
163
+ self._text_support_cache: _BoundedCache = _BoundedCache(maxsize=10_000)
164
+ self._measurement_draw = ImageDraw.Draw(Image.new(self._pil_mode, (1, 1)))
165
+ self._probe_failed_fonts: set[Any] = set()
166
+ self.last_rejection: str | None = None
167
+ if cfg.multilingual:
168
+ from PIL import features
169
+
170
+ if not features.check_feature("raqm"):
171
+ raise ValueError(
172
+ "multilingual mode requires Pillow with RAQM (HarfBuzz/FriBidi); install a RAQM-enabled Pillow build"
173
+ )
174
+ self._shaping_kwargs: dict[str, Any] = {}
175
+ if cfg.multilingual:
176
+ if cfg.direction != "auto":
177
+ self._shaping_kwargs["direction"] = cfg.direction
178
+ if cfg.shaping_language:
179
+ self._shaping_kwargs["language"] = cfg.shaping_language
180
+
181
+ # Font caching helpers
182
+
183
+ @staticmethod
184
+ def _font_cache_key(font: Any) -> Any:
185
+ font_path = getattr(font, "path", None)
186
+ font_size = getattr(font, "size", None)
187
+ if font_path is not None and font_size is not None:
188
+ return (str(font_path), int(font_size), int(getattr(font, "index", 0)))
189
+ return id(font)
190
+
191
+ def _get_reference_glyph_signature(self, font: Any) -> tuple[Any, Any]:
192
+ """Get cached signature of the font's undefined (tofu) glyph."""
193
+ font_key = self._font_cache_key(font)
194
+ if font_key in self._font_ref_cache:
195
+ return self._font_ref_cache[font_key]
196
+
197
+ undefined_chars = ["￿", "\U0010ffff", "\0"]
198
+ ref_signature = None
199
+ for uc in undefined_chars:
200
+ try:
201
+ ref_mask = font.getmask(uc)
202
+ if ref_mask:
203
+ bbox = ref_mask.getbbox()
204
+ if bbox is not None:
205
+ ref_signature = (bbox, bytes(ref_mask))
206
+ break
207
+ except Exception:
208
+ continue
209
+
210
+ if ref_signature is None:
211
+ ref_signature = (None, None)
212
+
213
+ self._font_ref_cache[font_key] = ref_signature
214
+ return ref_signature
215
+
216
+ def _is_char_supported(self, font: Any, char: str, ref_bbox: Any, ref_bytes: bytes) -> bool:
217
+ """Check if a font supports a single character."""
218
+ font_key = self._font_cache_key(font)
219
+ cache_key = (font_key, char)
220
+ cached = self._glyph_support_cache.get(cache_key)
221
+ if cached is not None:
222
+ return cached
223
+
224
+ try:
225
+ char_mask = font.getmask(char)
226
+ char_bbox = char_mask.getbbox()
227
+ if ref_bbox is None:
228
+ supported = char_bbox is not None
229
+ else:
230
+ supported = not (char_bbox == ref_bbox and bytes(char_mask) == ref_bytes)
231
+ except Exception:
232
+ supported = False
233
+
234
+ self._glyph_support_cache[cache_key] = supported
235
+ return supported
236
+
237
+ def _is_text_supported(self, font: Any, text: str) -> bool:
238
+ """Check if font supports all characters in text."""
239
+ try:
240
+ font_key = self._font_cache_key(font)
241
+ text_cache_key = (font_key, text)
242
+ cached = self._text_support_cache.get(text_cache_key)
243
+ if cached is not None:
244
+ return cached
245
+
246
+ reason = invalid_control(text)
247
+ if reason:
248
+ self.last_rejection = reason
249
+ return False
250
+ font_path = getattr(font, "path", None)
251
+ if font_path is not None:
252
+ reason = coverage_error(str(font_path), text, int(getattr(font, "index", 0)))
253
+ supported = reason is None
254
+ self.last_rejection = reason
255
+ self._text_support_cache[text_cache_key] = supported
256
+ return supported
257
+
258
+ ref_bbox, ref_bytes = self._get_reference_glyph_signature(font)
259
+ for char in text:
260
+ if not needs_glyph(char):
261
+ continue
262
+ if not self._is_char_supported(font, char, ref_bbox, ref_bytes):
263
+ self._text_support_cache[text_cache_key] = False
264
+ return False
265
+
266
+ self._text_support_cache[text_cache_key] = True
267
+ return True
268
+ except Exception as exc:
269
+ self.last_rejection = f"font coverage inspection failed: {exc}"
270
+ return False
271
+
272
+ def _image_is_blank(
273
+ self, img_array: np.ndarray, threshold: int = 150, min_ratio: float = 0.002
274
+ ) -> bool:
275
+ """Check if image has too few dark/text pixels."""
276
+ if img_array is None or img_array.size == 0:
277
+ return True
278
+ dark_pixels = np.sum(img_array < threshold)
279
+ return bool((dark_pixels / img_array.size) < min_ratio)
280
+
281
+ # Background/text colour sampling
282
+
283
+ def _sample_bg_and_text_colors(
284
+ self, augment: bool
285
+ ) -> tuple[int | tuple[int, int, int], int | tuple[int, int, int]]:
286
+ """Sample (bg_color, text_color) according to ``bg_color_mode``.
287
+
288
+ Palette catalogue
289
+ -----------------
290
+ default
291
+ Off-white / light grey background (235-255) with near-black text (0-30).
292
+ Always used when ``augment=False``.
293
+
294
+ paper_tones
295
+ Warm cream, aged sepia, recycled grey, or blueprint blue background
296
+ with dark text. Works in both grayscale (L) and RGB modes.
297
+
298
+ colored
299
+ Soft pastel backgrounds (light green, pink, yellow, cyan) with dark text.
300
+
301
+ dark_mode
302
+ Dark near-black background with light near-white text.
303
+
304
+ gradient
305
+ Same bg/text as 'default' but a gradient overlay is applied to the
306
+ canvas *after* rendering (handled in the render pipeline).
307
+ Falls back to default sampling here.
308
+
309
+ random
310
+ Randomly selects from all palettes (excluding 'gradient') when
311
+ ``augment=True``; falls back to 'default' when ``augment=False``.
312
+
313
+ To disable splitting entirely (100 % train), pass
314
+ ``--split-ratios 100 0 0`` or ``--val-percent 0 --test-percent 0``.
315
+ """
316
+ if not augment:
317
+ bg: int | tuple[int, int, int]
318
+ text: int | tuple[int, int, int]
319
+ if self._pil_mode == "RGB":
320
+ bg = (255, 255, 255)
321
+ text = (0, 0, 0)
322
+ else:
323
+ bg = 255
324
+ text = 0
325
+ return bg, text
326
+
327
+ mode = self._bg_color_mode
328
+ if mode == "random":
329
+ mode = random.choice(["default", "paper_tones", "colored", "dark_mode"])
330
+
331
+ if mode == "paper_tones":
332
+ palettes = [
333
+ ((248, 243, 230), (20, 15, 10)), # warm cream
334
+ ((242, 230, 205), (30, 20, 10)), # aged sepia
335
+ ((225, 225, 220), (25, 25, 30)), # recycled grey
336
+ ((228, 238, 248), (15, 20, 40)), # blueprint blue
337
+ ]
338
+ bg_rgb, text_rgb = random.choice(palettes)
339
+ if self._pil_mode == "RGB":
340
+ return bg_rgb, text_rgb
341
+ # Grayscale approximation
342
+ return (
343
+ int(0.299 * bg_rgb[0] + 0.587 * bg_rgb[1] + 0.114 * bg_rgb[2]),
344
+ int(0.299 * text_rgb[0] + 0.587 * text_rgb[1] + 0.114 * text_rgb[2]),
345
+ )
346
+
347
+ if mode == "colored":
348
+ palettes = [
349
+ ((230, 248, 230), (20, 40, 20)), # pastel green
350
+ ((248, 230, 240), (40, 15, 30)), # pastel pink
351
+ ((248, 248, 215), (35, 35, 10)), # pastel yellow
352
+ ((220, 240, 248), (15, 30, 45)), # pastel cyan
353
+ ]
354
+ bg_rgb, text_rgb = random.choice(palettes)
355
+ if self._pil_mode == "RGB":
356
+ return bg_rgb, text_rgb
357
+ return (
358
+ int(0.299 * bg_rgb[0] + 0.587 * bg_rgb[1] + 0.114 * bg_rgb[2]),
359
+ int(0.299 * text_rgb[0] + 0.587 * text_rgb[1] + 0.114 * text_rgb[2]),
360
+ )
361
+
362
+ if mode == "dark_mode":
363
+ if self._pil_mode == "RGB":
364
+ bg_rgb = (
365
+ random.randint(20, 45),
366
+ random.randint(20, 45),
367
+ random.randint(25, 50),
368
+ )
369
+ text_rgb = (
370
+ random.randint(210, 240),
371
+ random.randint(210, 240),
372
+ random.randint(215, 245),
373
+ )
374
+ return bg_rgb, text_rgb
375
+ bg_l = random.randint(20, 45)
376
+ text_l = random.randint(210, 240)
377
+ return bg_l, text_l
378
+
379
+ # mode == "default" or "gradient" (gradient uses default colors, overlay applied separately)
380
+ if self._pil_mode == "RGB":
381
+ v = random.randint(235, 255)
382
+ t = random.randint(0, 30)
383
+ return (v, v, v), (t, t, t)
384
+ return random.randint(235, 255), random.randint(0, 30)
385
+
386
+ # Text base rendering
387
+
388
+ def _sample_decorations(self, text: str) -> DecorStyle:
389
+ """Sample a per-line decoration state from ``cfg.text_deco``/``cfg.text_effect``."""
390
+ deco = self._cfg.text_deco
391
+ effect_cfg = self._cfg.text_effect
392
+ style = DecorStyle()
393
+ if not text or not (deco.enabled or effect_cfg.enabled):
394
+ return style
395
+
396
+ style.bold = random.random() < deco.bold_prob
397
+ style.italic = random.random() < deco.italic_prob
398
+ style.underline = random.random() < deco.underline_prob
399
+ if self.color_mode == 3:
400
+ style.color = random.random() < deco.color_prob
401
+
402
+ candidates = [i for i, ch in enumerate(text) if ch.isascii() and ch.isalnum()]
403
+ if candidates:
404
+ if random.random() < deco.subscript_prob:
405
+ style.sub_indices = random.sample(candidates, min(2, len(candidates)))
406
+ chosen = set(style.sub_indices)
407
+ candidates = [i for i in candidates if i not in chosen]
408
+ if candidates and random.random() < deco.superscript_prob:
409
+ style.super_indices = random.sample(candidates, min(2, len(candidates)))
410
+
411
+ if effect_cfg.enabled:
412
+ style.effect = self._sample_effect(effect_cfg)
413
+ return style
414
+
415
+ @staticmethod
416
+ def _sample_effect(cfg: TextEffectConfig) -> str | None:
417
+ """Weighted-pick at most one text effect: probabilities rolled in a fixed
418
+ order, first hit wins (Canva-style effects panels are single-select)."""
419
+ for name in TEXT_EFFECT_NAMES:
420
+ prob = getattr(cfg, f"{name}_prob")
421
+ if prob > 0.0 and random.random() < prob:
422
+ return name
423
+ return None
424
+
425
+ @staticmethod
426
+ def _sample_deco_color(bg_color: int | tuple[int, int, int]) -> tuple[int, int, int]:
427
+ """Pick a decoration color that contrasts with *bg_color*."""
428
+ if isinstance(bg_color, tuple):
429
+ lum = 0.299 * bg_color[0] + 0.587 * bg_color[1] + 0.114 * bg_color[2]
430
+ else:
431
+ lum = float(bg_color)
432
+ palette = _DECO_LIGHT_TEXT_COLORS if lum < 128 else _DECO_DARK_TEXT_COLORS
433
+ return random.choice(palette)
434
+
435
+ @staticmethod
436
+ def _luminance(color: int | tuple[int, ...]) -> float:
437
+ if isinstance(color, tuple):
438
+ return 0.299 * color[0] + 0.587 * color[1] + 0.114 * color[2]
439
+ return float(color)
440
+
441
+ @classmethod
442
+ def _contrast_color(cls, ref_color: int | tuple[int, int, int]) -> int | tuple[int, int, int]:
443
+ """Pick a color that contrasts with *ref_color*'s luminance."""
444
+ is_dark_ref = cls._luminance(ref_color) <= 128
445
+ if isinstance(ref_color, tuple):
446
+ palette = _DECO_LIGHT_TEXT_COLORS if is_dark_ref else _DECO_DARK_TEXT_COLORS
447
+ return random.choice(palette)
448
+ return 220 if is_dark_ref else 40
449
+
450
+ @staticmethod
451
+ def _lerp_color(
452
+ a: int | tuple[int, ...], b: int | tuple[int, ...], t: float
453
+ ) -> int | tuple[int, ...]:
454
+ t = max(0.0, min(1.0, t))
455
+ if isinstance(a, tuple) and isinstance(b, tuple):
456
+ return tuple(round(a[i] + (b[i] - a[i]) * t) for i in range(len(a)))
457
+ av = a if isinstance(a, (int, float)) else a[0]
458
+ bv = b if isinstance(b, (int, float)) else b[0]
459
+ return round(av + (bv - av) * t)
460
+
461
+ @staticmethod
462
+ def _scale_color(color: int | tuple[int, ...], factor: float) -> int | tuple[int, ...]:
463
+ factor = max(0.0, factor)
464
+ if isinstance(color, tuple):
465
+ return tuple(max(0, min(255, round(c * factor))) for c in color)
466
+ return max(0, min(255, round(color * factor)))
467
+
468
+ @staticmethod
469
+ def _deco_names(style: DecorStyle) -> list[str]:
470
+ """Active decoration/effect names for metadata (best-effort)."""
471
+ names: list[str] = []
472
+ if style.bold:
473
+ names.append("bold")
474
+ if style.italic:
475
+ names.append("italic")
476
+ if style.underline:
477
+ names.append("underline")
478
+ if style.color:
479
+ names.append("color")
480
+ if style.sub_indices:
481
+ names.append("subscript")
482
+ if style.super_indices:
483
+ names.append("superscript")
484
+ if style.effect:
485
+ names.append(style.effect)
486
+ return names
487
+
488
+ @staticmethod
489
+ def _effect_margin(effect: str | None, base_size: int) -> int:
490
+ """Extra padding (px) an effect needs so blur/offset/stroke never clips."""
491
+ if effect in ("outline", "hollow"):
492
+ return max(2, round(base_size * 0.09))
493
+ if effect == "shadow":
494
+ return max(3, round(base_size * 0.2))
495
+ if effect in ("glow", "neon"):
496
+ return max(4, round(base_size * 0.4))
497
+ if effect == "echo":
498
+ return max(4, round(base_size * 0.35))
499
+ if effect == "glitch":
500
+ return max(2, round(base_size * 0.08))
501
+ if effect == "background":
502
+ return max(3, round(base_size * 0.15))
503
+ return 0
504
+
505
+ def _composite_mask_effect(
506
+ self,
507
+ img: Image.Image,
508
+ mask: Image.Image,
509
+ effect: str,
510
+ fill: int | tuple[int, int, int],
511
+ bg_color: int | tuple[int, int, int],
512
+ base_size: int,
513
+ ) -> None:
514
+ """Composite a rasterized-mask effect (shadow/echo/glow/neon/glitch/pixel)
515
+ onto *img* in place. *mask* is an "L" image where 255 marks glyph ink."""
516
+ if effect == "shadow":
517
+ offset = max(2, round(base_size * 0.1))
518
+ shadow_color = self._scale_color(bg_color, 0.3)
519
+ shifted = Image.new("L", img.size, 0)
520
+ shifted.paste(mask, (offset, offset))
521
+ blur_r = max(1, round(base_size * 0.06))
522
+ shifted = shifted.filter(ImageFilter.GaussianBlur(blur_r))
523
+ img.paste(shadow_color, (0, 0), shifted)
524
+ img.paste(fill, (0, 0), mask)
525
+ return
526
+
527
+ if effect == "echo":
528
+ copies = random.randint(2, 3)
529
+ step = max(2, round(base_size * 0.09))
530
+ for i in range(copies, 0, -1):
531
+ shifted = Image.new("L", img.size, 0)
532
+ shifted.paste(mask, (step * i, step * i))
533
+ alpha_scale = 0.55 * (1 - (i - 1) / copies)
534
+ shifted = shifted.point(lambda v, s=alpha_scale: int(v * s))
535
+ img.paste(fill, (0, 0), shifted)
536
+ img.paste(fill, (0, 0), mask)
537
+ return
538
+
539
+ if effect in ("glow", "neon"):
540
+ glow_color = fill
541
+ if effect == "neon" and isinstance(fill, tuple):
542
+ glow_color = random.choice(_NEON_COLORS_RGB)
543
+ blur_r = max(3, round(base_size * (0.4 if effect == "neon" else 0.28)))
544
+ glow_mask = mask.filter(ImageFilter.GaussianBlur(blur_r))
545
+ glow_mask = glow_mask.point(lambda v: min(255, int(v * 2.2)))
546
+ img.paste(glow_color, (0, 0), glow_mask)
547
+ if effect == "neon":
548
+ tight = mask.filter(ImageFilter.GaussianBlur(max(1, blur_r // 3)))
549
+ tight = tight.point(lambda v: min(255, int(v * 1.6)))
550
+ img.paste(glow_color, (0, 0), tight)
551
+ img.paste(glow_color if effect == "neon" else fill, (0, 0), mask)
552
+ return
553
+
554
+ if effect == "glitch":
555
+ offset = min(3, max(1, round(base_size * 0.035)))
556
+ if isinstance(fill, tuple):
557
+ color_a, color_b = (255, 60, 60), (60, 220, 255)
558
+ else:
559
+ color_a, color_b = self._scale_color(fill, 1.2), self._scale_color(fill, 0.6)
560
+ left = Image.new("L", img.size, 0)
561
+ left.paste(mask, (-offset, 0))
562
+ right = Image.new("L", img.size, 0)
563
+ right.paste(mask, (offset, 0))
564
+ img.paste(color_a, (0, 0), left)
565
+ img.paste(color_b, (0, 0), right)
566
+ img.paste(fill, (0, 0), mask)
567
+ return
568
+
569
+ if effect == "pixel":
570
+ bbox = mask.getbbox()
571
+ if bbox is None:
572
+ return
573
+ x0, y0, x1, y1 = bbox
574
+ w, h = x1 - x0, y1 - y0
575
+ if w <= 0 or h <= 0:
576
+ return
577
+ factor = random.uniform(2.5, 4.5)
578
+ small_w = max(1, round(w / factor))
579
+ small_h = max(1, round(h / factor))
580
+ crop = mask.crop(bbox)
581
+ blocky = crop.resize((small_w, small_h), Image.Resampling.NEAREST).resize((w, h), Image.Resampling.NEAREST)
582
+ mask = mask.copy()
583
+ mask.paste(blocky, (x0, y0))
584
+ img.paste(fill, (0, 0), mask)
585
+ return
586
+
587
+ def _build_deco_runs(
588
+ self, text: str, base_font: Any, base_ascent: int, base_size: int, style: DecorStyle
589
+ ) -> list[tuple[str, Any, float]]:
590
+ """Split *text* into drawable runs: ``(segment, font, vertical offset dy)``.
591
+
592
+ Sub/superscript characters become their own runs at ~0.65x size with a
593
+ baseline offset; everything else is one contiguous run on the base font.
594
+ """
595
+ base_path = getattr(base_font, "path", None)
596
+ small_font = None
597
+ if base_path is not None:
598
+ small_font = self.font_manager.get_font_by_path_and_size(
599
+ base_path, max(8, round(base_size * 0.65))
600
+ )
601
+
602
+ sub_set = set(style.sub_indices)
603
+ super_set = set(style.super_indices)
604
+ # Subscript drop: spec says ~0.3 x descent; at typical metrics that is only
605
+ # ~0.06em (1-2px) and visually invisible. 0.18em is the visually-correct
606
+ # subscript drop and is what the spec's "~" allows.
607
+ sub_offset = round(base_size * 0.18)
608
+ super_offset = -round(base_ascent * 0.35) # raise by ~0.35 x ascent (spec)
609
+
610
+ runs: list[tuple[str, Any, float]] = []
611
+ seg: list[str] = []
612
+ for idx, ch in enumerate(text):
613
+ if idx in sub_set or idx in super_set:
614
+ if seg:
615
+ runs.append(("".join(seg), base_font, 0.0))
616
+ seg = []
617
+ font = small_font if small_font is not None else base_font
618
+ dy = sub_offset if idx in sub_set else super_offset
619
+ runs.append((ch, font, float(dy)))
620
+ else:
621
+ seg.append(ch)
622
+ if seg:
623
+ runs.append(("".join(seg), base_font, 0.0))
624
+ return runs
625
+
626
+ def _render_decorated(
627
+ self,
628
+ text: str,
629
+ style: DecorStyle,
630
+ augment: bool,
631
+ target_height: int,
632
+ retry_limit: int = 10,
633
+ ) -> tuple[np.ndarray, Any, np.ndarray] | None:
634
+ """Render a single line with decorations on the single-font path.
635
+
636
+ Bold/italic are applied only when a matching variant font exists; if none
637
+ does, the flag is cleared and the line renders with a regular font (other
638
+ decorations still apply). Returns ``(image, base_font, glyph_mask)``
639
+ or ``None`` on failure. Never raises.
640
+ """
641
+ try:
642
+ return self._render_decorated_impl(text, style, augment, target_height, retry_limit)
643
+ except Exception as exc:
644
+ _LOGGER.warning("text decoration rendering failed: %s", exc)
645
+ return None
646
+
647
+ def _render_decorated_impl(
648
+ self,
649
+ text: str,
650
+ style: DecorStyle,
651
+ augment: bool,
652
+ target_height: int,
653
+ retry_limit: int,
654
+ ) -> tuple[np.ndarray, Any, np.ndarray] | None:
655
+ # 1. Base font (variant when bold/italic requested and available).
656
+ if style.bold or style.italic:
657
+ desired: set[str] = set()
658
+ if style.bold:
659
+ desired.add("bold")
660
+ if style.italic:
661
+ desired.add("italic")
662
+ path = self.font_manager.random_font_path_with_style(text, desired)
663
+ variant = None
664
+ if path is not None:
665
+ if self.font_size_mode == "proportional":
666
+ size = max(8, round(target_height * sample_font_scale(self._cfg)))
667
+ else:
668
+ size = random.choice([28, 32, 36, 40, 44, 48])
669
+ variant = self.font_manager.get_font_by_path_and_size(path, size)
670
+ if path is not None and variant is not None and self._is_text_supported(variant, text):
671
+ font = variant
672
+ # A variant may satisfy only part of the request (e.g. bold-only
673
+ # fallback when bold+italic was requested): drop the styles the
674
+ # chosen font does not actually carry so metadata stays truthful.
675
+ chosen = self.font_manager._style_tags(path)
676
+ if style.bold and "bold" not in chosen:
677
+ style.bold = False
678
+ if style.italic and "italic" not in chosen:
679
+ style.italic = False
680
+ else:
681
+ style.bold = False
682
+ style.italic = False
683
+ font = self._select_font(text, target_height, retry_limit)
684
+ if font is None:
685
+ return None
686
+ else:
687
+ font = self._select_font(text, target_height, retry_limit)
688
+ if font is None:
689
+ return None
690
+
691
+ # 1b. "huge"/"tiny" effects resize the chosen font relative to itself,
692
+ # regardless of which branch above picked it (variant or plain).
693
+ if style.effect in _SIZE_EFFECTS:
694
+ font_path = getattr(font, "path", None)
695
+ if font_path is not None:
696
+ cur_size = int(getattr(font, "size", 28))
697
+ mult = (
698
+ random.uniform(1.6, 2.3)
699
+ if style.effect == "huge"
700
+ else random.uniform(0.35, 0.55)
701
+ )
702
+ new_size = max(8, min(400, round(cur_size * mult)))
703
+ resized = self.font_manager.get_font_by_path_and_size(font_path, new_size)
704
+ if resized is not None:
705
+ font = resized
706
+
707
+ if not self._is_text_supported(font, text):
708
+ return None
709
+ base_size = int(getattr(font, "size", 28))
710
+ try:
711
+ ascent, descent = font.getmetrics()
712
+ except Exception:
713
+ ascent, descent = font.getbbox(text)[3], 0
714
+
715
+ # 2. Run layout.
716
+ runs = self._build_deco_runs(text, font, ascent, base_size, style)
717
+ widths = [self._measurement_draw.textlength(seg, font=fnt) for seg, fnt, _ in runs]
718
+ total_w = round(sum(widths))
719
+ underline_th = max(1, base_size // 15)
720
+
721
+ # 3. Vertical extent relative to the shared baseline.
722
+ rel_top = 0
723
+ rel_bottom = 0
724
+ for (seg, fnt, dy), _w in zip(runs, widths, strict=True):
725
+ bbox = fnt.getbbox(seg)
726
+ try:
727
+ run_ascent, _run_descent = fnt.getmetrics()
728
+ except Exception:
729
+ run_ascent = bbox[3]
730
+ rel_top = min(rel_top, dy + bbox[1] - run_ascent)
731
+ rel_bottom = max(rel_bottom, dy + bbox[3] - run_ascent)
732
+ if style.underline:
733
+ rel_bottom = max(rel_bottom, descent + 2 + underline_th)
734
+
735
+ # 4. Canvas sizing (never clips); effects that draw outside the glyph
736
+ # ink (blur halos, offset copies, strokes) get extra margin.
737
+ effect_margin = self._effect_margin(style.effect, base_size)
738
+ padding_x = (random.randint(10, 30) if augment else 20) + effect_margin
739
+ padding_y = (random.randint(5, 15) if augment else 10) + effect_margin
740
+ img_w = max(1, total_w + padding_x * 2)
741
+ img_h = max(1, round((rel_bottom - rel_top) + padding_y * 2))
742
+
743
+ bg_color, text_color = self._sample_bg_and_text_colors(augment)
744
+ if style.color and self._pil_mode == "RGB":
745
+ fill = self._sample_deco_color(bg_color)
746
+ else:
747
+ fill = text_color
748
+
749
+ img = Image.new(self._pil_mode, (img_w, img_h), color=bg_color)
750
+ draw = ImageDraw.Draw(img)
751
+ baseline_y = padding_y - rel_top + (random.randint(-2, 2) if augment else 0)
752
+ start_x = padding_x + (random.randint(-3, 3) if augment else 0)
753
+
754
+ run_positions: list[tuple[str, Any, tuple[int | float, int]]] = []
755
+ cursor_x = start_x
756
+ for (seg, fnt, dy), w in zip(runs, widths, strict=True):
757
+ try:
758
+ run_ascent, _ = fnt.getmetrics()
759
+ except Exception:
760
+ run_ascent = fnt.getbbox(seg)[3]
761
+ run_positions.append((seg, fnt, (cursor_x, round(baseline_y + dy - run_ascent))))
762
+ cursor_x += w
763
+
764
+ # 5. Draw the line, dispatching on the sampled effect (if any).
765
+ effect = style.effect
766
+ if effect == "background":
767
+ box_color = self._contrast_color(fill)
768
+ pad = max(3, round(base_size * 0.12))
769
+ draw.rectangle(
770
+ [
771
+ start_x - pad,
772
+ baseline_y + rel_top - pad,
773
+ start_x + total_w + pad,
774
+ baseline_y + rel_bottom + pad,
775
+ ],
776
+ fill=box_color,
777
+ )
778
+ for seg, fnt, pos in run_positions:
779
+ draw.text(pos, seg, font=fnt, fill=fill)
780
+ elif effect in ("outline", "hollow"):
781
+ stroke_w = max(1, round(base_size * 0.07))
782
+ interior = fill if effect == "outline" else bg_color
783
+ stroke_color = self._contrast_color(fill) if effect == "outline" else fill
784
+ for seg, fnt, pos in run_positions:
785
+ draw.text(
786
+ pos,
787
+ seg,
788
+ font=fnt,
789
+ fill=interior,
790
+ stroke_width=stroke_w,
791
+ stroke_fill=stroke_color,
792
+ )
793
+ elif effect == "transparent":
794
+ alpha = random.uniform(0.4, 0.7)
795
+ blended = self._lerp_color(bg_color, fill, alpha)
796
+ for seg, fnt, pos in run_positions:
797
+ draw.text(pos, seg, font=fnt, fill=blended)
798
+ elif effect in _MASK_EFFECTS:
799
+ mask = Image.new("L", (img_w, img_h), 0)
800
+ mask_draw = ImageDraw.Draw(mask)
801
+ for seg, fnt, pos in run_positions:
802
+ mask_draw.text(pos, seg, font=fnt, fill=255)
803
+ self._composite_mask_effect(img, mask, effect, fill, bg_color, base_size)
804
+ else:
805
+ for seg, fnt, pos in run_positions:
806
+ draw.text(pos, seg, font=fnt, fill=fill)
807
+
808
+ # Generate glyph_mask for decorated text (ink = 255, background = 0, no underlines/background boxes)
809
+ glyph_mask_img = Image.new("L", (img_w, img_h), 0)
810
+ glyph_mask_draw = ImageDraw.Draw(glyph_mask_img)
811
+ for seg, fnt, pos in run_positions:
812
+ glyph_mask_draw.text(pos, seg, font=fnt, fill=255)
813
+ glyph_mask = np.array(glyph_mask_img)
814
+
815
+ if style.underline:
816
+ y_ul = baseline_y + descent + 2
817
+ draw.line([(start_x, y_ul), (start_x + total_w, y_ul)], fill=fill, width=underline_th)
818
+
819
+ return np.array(img), font, glyph_mask
820
+
821
+ def _render_clean_canvas(
822
+ self,
823
+ text: str,
824
+ font: Any,
825
+ augment: bool,
826
+ has_khmer: bool = False,
827
+ target_height: int | None = None,
828
+ ) -> tuple[np.ndarray, int, np.ndarray] | None:
829
+ """Render text on a clean canvas (no augmentation)."""
830
+ try:
831
+ bbox = font.getbbox(text, **self._shaping_kwargs)
832
+ text_w = bbox[2] - bbox[0]
833
+ text_h = bbox[3] - bbox[1]
834
+ offset_y = -bbox[1]
835
+ except Exception as exc:
836
+ if self._cfg.multilingual:
837
+ self.last_rejection = f"RAQM measurement failed: {exc}"
838
+ return None
839
+ text_w, text_h = font.getmask(text).size
840
+ offset_y = 0
841
+
842
+ padding_x = random.randint(10, 30) if augment else 20
843
+ if self.vertical_padding_mode == "random" and target_height:
844
+ ratio = sample_vertical_padding_ratio(self._cfg)
845
+ padding_y = max(1, round(target_height * ratio))
846
+ else:
847
+ padding_y = random.randint(5, 15) if augment else 10
848
+ img_w = max(1, text_w + padding_x * 2)
849
+ img_h = max(1, text_h + padding_y * 2)
850
+
851
+ bg_color, text_color = self._sample_bg_and_text_colors(augment)
852
+
853
+ img = Image.new(self._pil_mode, (img_w, img_h), color=bg_color)
854
+ draw = ImageDraw.Draw(img)
855
+ mask_img = Image.new("L", (img_w, img_h), color=0)
856
+ mask_draw = ImageDraw.Draw(mask_img)
857
+
858
+ x = padding_x + (random.randint(-3, 3) if augment else 0)
859
+ y = padding_y + offset_y + (random.randint(-2, 2) if augment else 0)
860
+ if self._cfg.multilingual:
861
+ x -= bbox[0]
862
+ draw.text((x, y), text, font=font, fill=text_color, **self._shaping_kwargs)
863
+ mask_draw.text((x, y), text, font=font, fill=255, **self._shaping_kwargs)
864
+
865
+ img_array = np.array(img)
866
+ mask_array = np.array(mask_img)
867
+ # Return bg as a scalar for compatibility; use 0th channel for RGB
868
+ bg_scalar = bg_color if isinstance(bg_color, int) else bg_color[0]
869
+ return img_array, bg_scalar, mask_array
870
+
871
+ # Mixed-font rendering
872
+
873
+ @staticmethod
874
+ def _split_text_into_spans(text: str) -> list[tuple[str, str]]:
875
+ """Split text into contiguous script spans."""
876
+ if not text:
877
+ return []
878
+
879
+ def _char_script(c: str) -> str:
880
+ cp = ord(c)
881
+ if (0x1780 <= cp <= 0x17FF) or (0x19E0 <= cp <= 0x19FF):
882
+ return "khmer"
883
+ if (0x41 <= cp <= 0x5A) or (0x61 <= cp <= 0x7A) or (0x30 <= cp <= 0x39):
884
+ return "english"
885
+ return "other"
886
+
887
+ spans: list[tuple[str, str]] = []
888
+ cur_script = _char_script(text[0])
889
+ cur_buf = text[0]
890
+ for ch in text[1:]:
891
+ s = _char_script(ch)
892
+ if s == "other" or s == cur_script:
893
+ cur_buf += ch
894
+ else:
895
+ spans.append((cur_buf, cur_script))
896
+ cur_script = s
897
+ cur_buf = ch
898
+ spans.append((cur_buf, cur_script))
899
+ return spans
900
+
901
+ def _render_mixed_font(
902
+ self, text: str, augment: bool, has_khmer: bool
903
+ ) -> tuple[np.ndarray, Any, list[str]] | None:
904
+ """Render with per-span font selection for mixed Khmer/English text."""
905
+ spans = (
906
+ _ra.split_text_spans(text) if _ra.HAS_RUST_ACCEL else self._split_text_into_spans(text)
907
+ )
908
+ if len(spans) <= 1:
909
+ return None
910
+
911
+ scripts_present = {s for _, s in spans if s != "other"}
912
+ if len(scripts_present) <= 1:
913
+ return None
914
+
915
+ first_script = next((s for _, s in spans if s != "other"), "khmer")
916
+ result = self.font_manager.get_random_font_for_script(first_script)
917
+ if result[0] is None or result[1] is None:
918
+ return None
919
+ base_font, base_size = result
920
+
921
+ padding_x = random.randint(10, 30) if augment else 20
922
+ padding_y = random.randint(5, 15) if augment else 10
923
+ bg_color, text_color = self._sample_bg_and_text_colors(augment)
924
+
925
+ # Measure spans
926
+ span_texts: list[str] = []
927
+ span_fonts: list[Any] = []
928
+ span_bboxes: list[tuple[int, int, int, int]] = []
929
+ span_ascents: list[int] = []
930
+ for span_text, script in spans:
931
+ if script == "other" or script == first_script:
932
+ font = base_font
933
+ else:
934
+ alt_result = self.font_manager.get_random_font_for_script(script)
935
+ if alt_result[0] is None:
936
+ return None
937
+ alt_font, _ = alt_result
938
+ alt_path = getattr(alt_font, "path", None)
939
+ if alt_path:
940
+ sized = self.font_manager.get_font_by_path_and_size(alt_path, base_size)
941
+ font = sized if sized is not None else alt_font
942
+ else:
943
+ font = alt_font
944
+
945
+ if not self._is_text_supported(font, span_text):
946
+ return None
947
+
948
+ try:
949
+ bbox = font.getbbox(span_text)
950
+ except Exception:
951
+ try:
952
+ w, h = font.getmask(span_text).size
953
+ bbox = (0, 0, w, h)
954
+ except Exception:
955
+ return None
956
+
957
+ try:
958
+ ascent, _descent = font.getmetrics()
959
+ except Exception:
960
+ ascent = bbox[3]
961
+
962
+ span_texts.append(span_text)
963
+ span_fonts.append(font)
964
+ span_bboxes.append(bbox)
965
+ span_ascents.append(ascent)
966
+
967
+ total_text_w = sum(b[2] - b[0] for b in span_bboxes)
968
+ if total_text_w <= 0:
969
+ return None
970
+
971
+ # Align spans on a shared baseline using each font's ascent metric.
972
+ # Top-aligning the raw ink bboxes (the old behaviour) breaks down
973
+ # across scripts: Khmer's stacked diacritics push its bbox top much
974
+ # higher than Latin's, so a shared bbox-top anchor leaves the Latin
975
+ # span floating well above the Khmer baseline instead of sitting on it.
976
+ above_baseline = [
977
+ max(0, ascent - bbox[1]) for ascent, bbox in zip(span_ascents, span_bboxes, strict=True)
978
+ ]
979
+ below_baseline = [
980
+ max(0, bbox[3] - ascent) for ascent, bbox in zip(span_ascents, span_bboxes, strict=True)
981
+ ]
982
+ max_above = max(above_baseline) if above_baseline else 0
983
+ max_below = max(below_baseline) if below_baseline else 0
984
+ if max_above + max_below <= 0:
985
+ return None
986
+
987
+ img_w = total_text_w + padding_x * 2
988
+ img_h = max_above + max_below + padding_y * 2
989
+
990
+ img = Image.new(self._pil_mode, (img_w, img_h), color=bg_color)
991
+ draw = ImageDraw.Draw(img)
992
+ x = padding_x + (random.randint(-3, 3) if augment else 0)
993
+ baseline_y = padding_y + max_above + (random.randint(-2, 2) if augment else 0)
994
+
995
+ for span_text, font, bbox, ascent in zip(
996
+ span_texts, span_fonts, span_bboxes, span_ascents, strict=False
997
+ ):
998
+ draw.text((x, baseline_y - ascent), span_text, font=font, fill=text_color)
999
+ x += bbox[2] - bbox[0]
1000
+
1001
+ paths = list(dict.fromkeys(str(f.path) for f in span_fonts if getattr(f, "path", None)))
1002
+ return np.array(img), base_font, paths
1003
+
1004
+ # Font selection
1005
+
1006
+ def eligible_font_paths(self, text: str) -> list[str]:
1007
+ """All cmap-eligible whole-line faces, independent of random retries."""
1008
+ paths = sorted({entry[0] for entry in self.font_manager._pool_for(text)})
1009
+ eligible = []
1010
+ reason = "selected font pool is empty"
1011
+ for path in paths:
1012
+ error = coverage_error(path, text, 0)
1013
+ if error is None:
1014
+ eligible.append(path)
1015
+ else:
1016
+ reason = error
1017
+ self.last_rejection = None if eligible else reason
1018
+ return eligible
1019
+
1020
+ def is_line_eligible(self, text: str) -> bool:
1021
+ """Check the coverage policy used by the configured rendering path."""
1022
+ if not self._cfg.cluster_font_fallback:
1023
+ return bool(self.eligible_font_paths(text))
1024
+ paths = sorted({entry[0] for entry in self.font_manager._pool_for(text)})
1025
+ self.last_rejection = check_cluster_fallback_coverage(text, paths)
1026
+ return self.last_rejection is None
1027
+
1028
+ def _select_font(self, text: str, target_height: int, retry_limit: int) -> Any | None:
1029
+ """Pick a font for *text*, sized proportionally to *target_height* when configured."""
1030
+ if self._cfg.multilingual:
1031
+ paths = self.eligible_font_paths(text)
1032
+ random.shuffle(paths)
1033
+ for path in paths:
1034
+ size = (
1035
+ max(8, round(target_height * sample_font_scale(self._cfg)))
1036
+ if self.font_size_mode == "proportional"
1037
+ else random.choice(self.font_manager._STANDARD_SIZES)
1038
+ )
1039
+ candidate = self.font_manager.get_font_by_path_and_size(path, size)
1040
+ if candidate is not None and self._is_text_supported(candidate, text):
1041
+ return candidate
1042
+ self.last_rejection = self.last_rejection or "no loadable font covers the whole line"
1043
+ return None
1044
+ if self.font_size_mode == "proportional":
1045
+ pool = self.font_manager._pool_for(text)
1046
+ if not pool:
1047
+ return None
1048
+ for _ in range(retry_limit):
1049
+ scale = sample_font_scale(self._cfg)
1050
+ desired_size = max(8, round(target_height * scale))
1051
+ font_path, _, _ = random.choice(pool)
1052
+ candidate = self.font_manager.get_font_by_path_and_size(font_path, desired_size)
1053
+ if candidate is not None and self._is_text_supported(candidate, text):
1054
+ return candidate
1055
+ return None
1056
+
1057
+ for _ in range(retry_limit):
1058
+ candidate = self.font_manager.get_random_font(text)
1059
+ if candidate and self._is_text_supported(candidate, text):
1060
+ return candidate
1061
+ return None
1062
+
1063
+ def _sample_target_height(self) -> int:
1064
+ return sample_line_height(self._cfg)
1065
+
1066
+ # Main render entrypoint
1067
+
1068
+ def render(
1069
+ self,
1070
+ text: str,
1071
+ augment: bool = True,
1072
+ specific_font: Any = None,
1073
+ retry_limit: int = 10,
1074
+ ) -> np.ndarray | None:
1075
+ """Render text to an image.
1076
+
1077
+ Returns a grayscale HxW uint8 array, or None if rendering fails.
1078
+ """
1079
+ clean = self._render_clean(text, augment, specific_font, retry_limit)
1080
+ return clean[0] if clean is not None else None
1081
+
1082
+ def render_clean_with_meta(
1083
+ self,
1084
+ text: str,
1085
+ specific_font: Any = None,
1086
+ retry_limit: int = 10,
1087
+ ) -> tuple[np.ndarray, int, dict[str, Any]] | None:
1088
+ """Render *text* on a clean canvas (no augmentation) plus metadata.
1089
+
1090
+ The image is the same clean canvas used by the generation pipeline
1091
+ before augmentation; layout composition uses it so annotations stay
1092
+ line-level and untransformed. Returns ``(image, target_height, meta)``
1093
+ or ``None`` when no font can render the line.
1094
+ """
1095
+ return self._render_clean(text, False, specific_font, retry_limit)
1096
+
1097
+ def _render_clean(
1098
+ self,
1099
+ text: str,
1100
+ augment: bool,
1101
+ specific_font: Any,
1102
+ retry_limit: int,
1103
+ ) -> tuple[np.ndarray, int, dict[str, Any]] | None:
1104
+ """Render text on a clean canvas at a sampled target height.
1105
+
1106
+ Returns `(image, target_height, metadata)` where *metadata* carries
1107
+ best-effort font info for the optional metadata sidecar, or `None` if
1108
+ rendering fails.
1109
+ """
1110
+ target_height = self._sample_target_height()
1111
+
1112
+ if specific_font:
1113
+ font = self.font_manager.get_font_by_ref(specific_font)
1114
+ if font is None or not self._is_text_supported(font, text):
1115
+ return None
1116
+ else:
1117
+ style = self._sample_decorations(text)
1118
+ if style.active:
1119
+ dec_res = self._render_decorated(text, style, augment, target_height, retry_limit)
1120
+ if dec_res is not None:
1121
+ deco_img, deco_font, deco_mask = dec_res
1122
+ img, mask = self._resize_image_and_mask(deco_img, deco_mask, target_height)
1123
+ meta = {
1124
+ "font": getattr(deco_font, "path", None),
1125
+ "font_size": getattr(deco_font, "size", None),
1126
+ "decorations": self._deco_names(style),
1127
+ "glyph_mask": mask,
1128
+ }
1129
+ meta["fonts"] = [meta["font"]] if meta["font"] else []
1130
+ return img, target_height, meta
1131
+ # Cluster-aware font fallback
1132
+ if self._cfg.cluster_font_fallback:
1133
+ clusters = split_grapheme_clusters(text)
1134
+ size = (
1135
+ max(8, round(target_height * sample_font_scale(self._cfg)))
1136
+ if self.font_size_mode == "proportional"
1137
+ else random.choice(self.font_manager._STANDARD_SIZES)
1138
+ )
1139
+ pool_paths = sorted({entry[0] for entry in self.font_manager._pool_for(text)})
1140
+ random.shuffle(pool_paths)
1141
+ primary_font = None
1142
+ fallback_fonts = []
1143
+ for p in pool_paths:
1144
+ f = self.font_manager.get_font_by_path_and_size(p, size)
1145
+ if f is not None:
1146
+ if primary_font is None:
1147
+ primary_font = f
1148
+ else:
1149
+ fallback_fonts.append(f)
1150
+ if primary_font is not None:
1151
+ cluster_runs = find_fallback_fonts_for_clusters(clusters, primary_font, fallback_fonts)
1152
+ if not cluster_runs:
1153
+ self.last_rejection = "font pool cannot cover every grapheme cluster"
1154
+ return None
1155
+ if len(cluster_runs) == 1:
1156
+ font = cluster_runs[0][1]
1157
+ else:
1158
+ visual_runs = resolve_bidi_runs(text, cluster_runs, self._cfg.direction)
1159
+ run_bboxes: list[tuple[int, int, int, int]] = []
1160
+ run_ascents: list[int] = []
1161
+ for run_text, run_font, run_direction in visual_runs:
1162
+ try:
1163
+ bbox = run_font.getbbox(run_text, **{**self._shaping_kwargs, "direction": run_direction})
1164
+ except Exception:
1165
+ bbox = (0, 0, run_font.getmask(run_text).size[0], run_font.getmask(run_text).size[1])
1166
+ try:
1167
+ ascent, _ = run_font.getmetrics()
1168
+ except Exception:
1169
+ ascent = bbox[3]
1170
+ run_bboxes.append(bbox)
1171
+ run_ascents.append(ascent)
1172
+
1173
+ above = [ascent - bbox[1] for ascent, bbox in zip(run_ascents, run_bboxes, strict=True)]
1174
+ below = [bbox[3] - ascent for ascent, bbox in zip(run_ascents, run_bboxes, strict=True)]
1175
+ max_above = max(above) if above else 0
1176
+ max_below = max(below) if below else 0
1177
+ total_text_w = sum(bbox[2] - bbox[0] for bbox in run_bboxes)
1178
+ if total_text_w <= 0:
1179
+ self.last_rejection = "font runs have no visible width"
1180
+ return None
1181
+ if total_text_w > 0:
1182
+ padding_x = random.randint(10, 30) if augment else 20
1183
+ if self.vertical_padding_mode == "random" and target_height:
1184
+ ratio = sample_vertical_padding_ratio(self._cfg)
1185
+ padding_y = max(1, round(target_height * ratio))
1186
+ else:
1187
+ padding_y = random.randint(5, 15) if augment else 10
1188
+
1189
+ img_w = max(1, total_text_w + padding_x * 2)
1190
+ img_h = max(1, max_above + max_below + padding_y * 2)
1191
+
1192
+ bg_color, text_color = self._sample_bg_and_text_colors(augment)
1193
+ img_pil = Image.new(self._pil_mode, (img_w, img_h), color=bg_color)
1194
+ draw_pil = ImageDraw.Draw(img_pil)
1195
+ mask_pil = Image.new("L", (img_w, img_h), color=0)
1196
+ mask_draw_pil = ImageDraw.Draw(mask_pil)
1197
+
1198
+ cur_x = padding_x + (random.randint(-3, 3) if augment else 0)
1199
+ baseline_y = padding_y + max_above + (random.randint(-2, 2) if augment else 0)
1200
+
1201
+ for (run_text, run_font, run_direction), bbox, ascent in zip(
1202
+ visual_runs, run_bboxes, run_ascents, strict=True
1203
+ ):
1204
+ pos = (cur_x - bbox[0], baseline_y - ascent)
1205
+ kwargs: dict[str, Any] = {**self._shaping_kwargs, "direction": run_direction}
1206
+ draw_pil.text(pos, run_text, font=run_font, fill=text_color, **kwargs)
1207
+ mask_draw_pil.text(pos, run_text, font=run_font, fill=255, **kwargs)
1208
+ cur_x += bbox[2] - bbox[0]
1209
+
1210
+ img, mask = self._resize_image_and_mask(
1211
+ np.array(img_pil), np.array(mask_pil), target_height
1212
+ )
1213
+ meta = {
1214
+ "font": getattr(primary_font, "path", None),
1215
+ "font_size": getattr(primary_font, "size", None),
1216
+ "fonts": list(dict.fromkeys(getattr(f, "path", None) for _, f in cluster_runs)),
1217
+ "glyph_mask": mask,
1218
+ }
1219
+ return img, target_height, meta
1220
+
1221
+ else:
1222
+ self.last_rejection = "selected font pool has no loadable fonts"
1223
+ return None
1224
+ else:
1225
+ font = self._select_font(text, target_height, retry_limit)
1226
+ if font is None:
1227
+ return None
1228
+
1229
+ has_khmer = any("ក" <= c <= "៿" for c in text)
1230
+
1231
+ # Try mixed-font rendering
1232
+ if (
1233
+ not specific_font
1234
+ and self.mixed_font_prob > 0.0
1235
+ and random.random() < self.mixed_font_prob
1236
+ ):
1237
+ mixed_result = self._render_mixed_font(text, augment, has_khmer)
1238
+ if mixed_result is not None:
1239
+ mixed_img, mixed_font, mixed_paths = mixed_result
1240
+ img = self._resize_to_target(mixed_img, target_height)
1241
+ meta = {
1242
+ "font": getattr(mixed_font, "path", None),
1243
+ "font_size": getattr(mixed_font, "size", None),
1244
+ "fonts": mixed_paths,
1245
+ }
1246
+ return img, target_height, meta
1247
+
1248
+ result = self._render_clean_canvas(text, font, augment, has_khmer, target_height)
1249
+ if result is None:
1250
+ return None
1251
+ img_array, _, mask_array = result
1252
+
1253
+ img, mask = self._resize_image_and_mask(img_array, mask_array, target_height)
1254
+ meta = {
1255
+ "font": getattr(font, "path", None),
1256
+ "font_size": getattr(font, "size", None),
1257
+ "glyph_mask": mask,
1258
+ }
1259
+ meta["fonts"] = [meta["font"]] if meta["font"] else []
1260
+ return img, target_height, meta
1261
+
1262
+ @staticmethod
1263
+ def _measure_line_ink_height(img: np.ndarray) -> int:
1264
+ """Visible line-ink extent on a known white, undecorated render.
1265
+
1266
+ Count the inclusive row span of pixels darker than 128 after output
1267
+ resizing. This excludes faint interpolation fringes and padding. It is
1268
+ a line extent, not the height of the smallest glyph or a font size.
1269
+ Never use this estimator on arbitrary backgrounds or decorated text.
1270
+ """
1271
+ ink = np.any(img < 128, axis=2) if img.ndim == 3 else img < 128
1272
+ rows = np.flatnonzero(np.any(ink, axis=1))
1273
+ return int(rows[-1] - rows[0] + 1) if rows.size else 0
1274
+
1275
+ def _augmentation_allowed(self, method_name: str, text_height: int | None) -> bool:
1276
+ minimum = max(
1277
+ self._cfg.min_text_height_for_augmentation,
1278
+ self._cfg.min_glyph_height_for_augmentation,
1279
+ )
1280
+ return (
1281
+ minimum == 0
1282
+ or method_name not in TEXT_HEIGHT_GUARDED_METHODS
1283
+ or (text_height is not None and text_height >= minimum)
1284
+ )
1285
+
1286
+ def _augmentation_text_height(self, clean: np.ndarray, meta: dict[str, Any]) -> int | None:
1287
+ min_guard = max(
1288
+ self._cfg.min_text_height_for_augmentation,
1289
+ self._cfg.min_glyph_height_for_augmentation,
1290
+ )
1291
+ if min_guard == 0:
1292
+ return None
1293
+
1294
+ glyph_mask = meta.get("glyph_mask")
1295
+ if glyph_mask is not None and isinstance(glyph_mask, np.ndarray):
1296
+ active_rows = np.flatnonzero(np.any(glyph_mask > 0, axis=1))
1297
+ return int(active_rows[-1] - active_rows[0] + 1) if active_rows.size else 0
1298
+
1299
+ # Effects/underlines can inflate image ink independently of glyph size.
1300
+ # Until those paths carry a glyph mask, conservatively treat as unknown.
1301
+ if "decorations" in meta:
1302
+ return None
1303
+ return self._measure_line_ink_height(clean)
1304
+ def render_with_one_augmentation(
1305
+ self,
1306
+ text: str,
1307
+ enabled_methods: list[tuple[str, AugMethodConfig]],
1308
+ specific_font: Any = None,
1309
+ retry_limit: int = 10,
1310
+ ) -> tuple[str, np.ndarray, dict[str, Any]] | None:
1311
+ """Render text to a clean canvas, then apply exactly one augmentation.
1312
+
1313
+ The augmentation method is chosen probabilistically from *enabled_methods* weighted by each method's `prob` field.
1314
+ Returns `(method_name, image, metadata)` or `None` if rendering fails or no method is selected.
1315
+ """
1316
+ clean_result = self._render_clean(text, False, specific_font, retry_limit)
1317
+ if clean_result is None:
1318
+ return None
1319
+ clean, target_height, meta = clean_result
1320
+
1321
+ text_height = self._augmentation_text_height(clean, meta)
1322
+ if self._cfg.clean_prob > 0 and random.random() < self._cfg.clean_prob:
1323
+ return (
1324
+ "clean",
1325
+ clean,
1326
+ {
1327
+ **meta,
1328
+ "width": int(clean.shape[1]),
1329
+ "height": int(clean.shape[0]),
1330
+ "augmentation": "clean",
1331
+ "augmentation_intensity": None,
1332
+ "text_height": text_height,
1333
+ "augmentation_reason": "clean_probability",
1334
+ },
1335
+ )
1336
+ # Filter before sampling either the method or its intensity.
1337
+ methods = [
1338
+ (n, c)
1339
+ for n, c in enabled_methods
1340
+ if c.enabled and self._augmentation_allowed(n, text_height)
1341
+ ]
1342
+ if not methods:
1343
+ if (
1344
+ self._cfg.min_text_height_for_augmentation > 0
1345
+ or self._cfg.min_glyph_height_for_augmentation > 0
1346
+ or self._cfg.multilingual
1347
+ ):
1348
+ meta = {
1349
+ **meta,
1350
+ "width": int(clean.shape[1]),
1351
+ "height": int(clean.shape[0]),
1352
+ "augmentation": "clean",
1353
+ "augmentation_intensity": None,
1354
+ "text_height": text_height,
1355
+ "augmentation_reason": "no_eligible_method",
1356
+ }
1357
+ return "clean", clean, meta
1358
+ return None
1359
+
1360
+ names = [n for n, _ in methods]
1361
+ weights = [c.prob for _, c in methods]
1362
+ total_weight = sum(weights)
1363
+ if total_weight <= 0.0:
1364
+ return None
1365
+
1366
+ # Normalize and pick one
1367
+ r = random.random() * total_weight
1368
+ cumulative = 0.0
1369
+ chosen_name = names[0]
1370
+ chosen_cfg = methods[0][1]
1371
+ for name, cfg in methods:
1372
+ cumulative += cfg.prob
1373
+ if r <= cumulative:
1374
+ chosen_name = name
1375
+ chosen_cfg = cfg
1376
+ break
1377
+
1378
+ intensity = chosen_cfg.sample_intensity()
1379
+ detected_script = detect_script(text)
1380
+ intensity = scale_intensity_for_script(
1381
+ intensity, detected_script, self._cfg.script_intensity_scales, chosen_name,
1382
+ font=meta.get("font"), font_scales=self._cfg.font_intensity_scales,
1383
+ )
1384
+ aug_img = self._apply_augmentation(
1385
+ clean, chosen_name, intensity, target_height, text_height=text_height
1386
+ )
1387
+ if aug_img is None:
1388
+ return None
1389
+
1390
+ meta = {
1391
+ **meta,
1392
+ "width": int(aug_img.shape[1]),
1393
+ "height": int(aug_img.shape[0]),
1394
+ "augmentation": chosen_name,
1395
+ "augmentation_intensity": intensity,
1396
+ "text_height": text_height,
1397
+ "augmentation_reason": "weighted_selection",
1398
+ }
1399
+ return chosen_name, aug_img, meta
1400
+
1401
+ def render_with_augmentations(
1402
+ self,
1403
+ text: str,
1404
+ enabled_methods: list[tuple[str, AugMethodConfig]],
1405
+ retry_limit: int = 10,
1406
+ ) -> list[tuple[str, np.ndarray, dict[str, Any]]]:
1407
+ """Render text to a clean canvas, then produce one image per enabled method.
1408
+
1409
+ Returns a list of `(method_name, image_array, metadata)` tuples.
1410
+ Each image has exactly one augmentation applied.
1411
+ """
1412
+ clean_result = self._render_clean(text, False, None, retry_limit)
1413
+ if clean_result is None:
1414
+ return []
1415
+ clean, target_height, meta = clean_result
1416
+
1417
+ text_height = self._augmentation_text_height(clean, meta)
1418
+ results: list[tuple[str, np.ndarray, dict[str, Any]]] = []
1419
+ for method_name, method_cfg in enabled_methods:
1420
+ if not method_cfg.enabled or not self._augmentation_allowed(method_name, text_height):
1421
+ continue
1422
+
1423
+ intensity = method_cfg.sample_intensity()
1424
+ detected_script = detect_script(text)
1425
+ intensity = scale_intensity_for_script(
1426
+ intensity, detected_script, self._cfg.script_intensity_scales, method_name,
1427
+ font=meta.get("font"), font_scales=self._cfg.font_intensity_scales,
1428
+ )
1429
+ aug_img = self._apply_augmentation(
1430
+ clean, method_name, intensity, target_height, text_height=text_height
1431
+ )
1432
+ if aug_img is not None:
1433
+ sample_meta = {
1434
+ **meta,
1435
+ "width": int(aug_img.shape[1]),
1436
+ "height": int(aug_img.shape[0]),
1437
+ }
1438
+ results.append((method_name, aug_img, sample_meta))
1439
+
1440
+ if (
1441
+ not results
1442
+ and self._cfg.min_text_height_for_augmentation > 0
1443
+ and not any(
1444
+ c.enabled and self._augmentation_allowed(n, text_height) for n, c in enabled_methods
1445
+ )
1446
+ ):
1447
+ sample_meta = {**meta, "width": int(clean.shape[1]), "height": int(clean.shape[0])}
1448
+ results.append(("clean", clean, sample_meta))
1449
+ return results
1450
+
1451
+ def _apply_augmentation(
1452
+ self,
1453
+ img: np.ndarray,
1454
+ method_name: str,
1455
+ intensity: float,
1456
+ target_height: int | None = None,
1457
+ *,
1458
+ text_height: int | None = None,
1459
+ ) -> np.ndarray | None:
1460
+ """Apply one method, enforcing the guard before optional native dispatch."""
1461
+ if not self._augmentation_allowed(method_name, text_height):
1462
+ return None
1463
+ aug_fn = AUG_METHODS.get(method_name)
1464
+ if aug_fn is None:
1465
+ return None
1466
+ if self._cfg.seed is not None and aug_fn in _RUST_ACCEL_FUNCTIONS:
1467
+ aug_fn = PYTHON_AUG_METHODS.get(method_name, aug_fn)
1468
+
1469
+ try:
1470
+ if method_name in _RGB_PREFERRED_METHODS and img.ndim == 2:
1471
+ # Grayscale image + RGB-requiring method: convert, augment, convert back
1472
+ rgb = cv2.cvtColor(img, cv2.COLOR_GRAY2RGB)
1473
+ result = aug_fn(rgb, intensity)
1474
+ if result is not None and result.ndim == 3:
1475
+ result = cv2.cvtColor(result, cv2.COLOR_RGB2GRAY)
1476
+ else:
1477
+ # RGB image or method works on any channel count. AUG_METHODS
1478
+ # entries never mutate their input in place -- native Rust
1479
+ # bindings take it as an immutable slice, and the pure-Python
1480
+ # fallbacks that need scratch space copy internally (e.g.
1481
+ # apply_salt_pepper) -- so no defensive copy is needed here.
1482
+ result = aug_fn(img, intensity)
1483
+
1484
+ return self._resize_to_target(result, target_height)
1485
+ except Exception as exc:
1486
+ _LOGGER.warning("augmentation %r failed: %s", method_name, exc)
1487
+ return None
1488
+
1489
+ # Augment existing image (image-dir mode)
1490
+
1491
+ def augment_image(
1492
+ self,
1493
+ img_array: np.ndarray,
1494
+ enabled_methods: list[tuple[str, AugMethodConfig]],
1495
+ mask: np.ndarray | None = None,
1496
+ script: str | None = None,
1497
+ font: str | None = None,
1498
+ ) -> list[tuple[str, np.ndarray]]:
1499
+ """Apply isolated augmentations to an existing image.
1500
+
1501
+ Existing images have unknown glyph height unless an explicit binary *mask*
1502
+ is provided. If *mask* is supplied, glyph height is computed from the mask.
1503
+ Returns one image per eligible method, or clean when none are eligible.
1504
+ """
1505
+ text_height: int | None = None
1506
+ if mask is not None and isinstance(mask, np.ndarray):
1507
+ active_rows = np.flatnonzero(np.any(mask > 0, axis=1))
1508
+ text_height = int(active_rows[-1] - active_rows[0] + 1) if active_rows.size else 0
1509
+
1510
+ min_guard = max(
1511
+ self._cfg.min_text_height_for_augmentation,
1512
+ self._cfg.min_glyph_height_for_augmentation,
1513
+ )
1514
+
1515
+ results: list[tuple[str, np.ndarray]] = []
1516
+ for method_name, method_cfg in enabled_methods:
1517
+ if not method_cfg.enabled or not self._augmentation_allowed(method_name, text_height):
1518
+ continue
1519
+
1520
+ intensity = method_cfg.sample_intensity()
1521
+ intensity = scale_intensity_for_script(
1522
+ intensity, script, self._cfg.script_intensity_scales, method_name,
1523
+ font=font, font_scales=self._cfg.font_intensity_scales,
1524
+ )
1525
+ aug_img = self._apply_augmentation(img_array, method_name, intensity, text_height=text_height)
1526
+ if aug_img is not None:
1527
+ results.append((method_name, aug_img))
1528
+
1529
+ if (
1530
+ not results
1531
+ and min_guard > 0
1532
+ and not any(
1533
+ c.enabled and self._augmentation_allowed(n, text_height) for n, c in enabled_methods
1534
+ )
1535
+ ):
1536
+ results.append(("clean", img_array.copy()))
1537
+ return results
1538
+
1539
+ # Resize to target dimensions
1540
+
1541
+ def _resize_to_target(self, img: np.ndarray, target_height: int | None = None) -> np.ndarray:
1542
+ """Resize image to target height, optionally to fixed width.
1543
+
1544
+ *target_height* defaults to `self.image_height` (the fixed-mode canvas
1545
+ height); callers on the variable-height path pass the per-sample
1546
+ sampled height instead. Scaling (never cropping) the whole canvas to
1547
+ this height is what keeps glyphs from ever being clipped: the drawn
1548
+ text always fits inside its clean canvas by construction, and a
1549
+ uniform resize preserves that.
1550
+ """
1551
+ return self._resize_image_and_mask(img, None, target_height)[0]
1552
+
1553
+ def _resize_image_and_mask(
1554
+ self, img: np.ndarray, mask: np.ndarray | None, target_height: int | None = None
1555
+ ) -> tuple[np.ndarray, np.ndarray | None]:
1556
+ """Apply the same resize and sampled placement to pixels and glyph coverage."""
1557
+ h, w = img.shape[:2]
1558
+ if h <= 0:
1559
+ return img, mask
1560
+
1561
+ th = target_height if target_height is not None else self.image_height
1562
+ scale = th / h
1563
+ new_w = max(1, round(w * scale))
1564
+ img = cv2.resize(img, (new_w, th), interpolation=cv2.INTER_LINEAR)
1565
+ if mask is not None:
1566
+ mask = cv2.resize(mask, (new_w, th), interpolation=cv2.INTER_NEAREST)
1567
+
1568
+ if self.image_width is None:
1569
+ return img, mask
1570
+
1571
+ if new_w < self.image_width:
1572
+ bg_val = self._estimate_bg(img)
1573
+ border_val: tuple[float, ...] = (
1574
+ (float(bg_val),) if img.ndim == 2 else (float(bg_val),) * img.shape[2]
1575
+ )
1576
+ x_offset = 0
1577
+ if self.random_align_when_padded:
1578
+ remaining = self.image_width - new_w
1579
+ x_offset = random.choice([0, remaining // 2, remaining])
1580
+ left_pad = int(max(0, x_offset))
1581
+ right_pad = int(max(0, self.image_width - (x_offset + new_w)))
1582
+ img = cv2.copyMakeBorder(
1583
+ img,
1584
+ top=0,
1585
+ bottom=0,
1586
+ left=left_pad,
1587
+ right=right_pad,
1588
+ borderType=cv2.BORDER_CONSTANT,
1589
+ value=border_val,
1590
+ )
1591
+ if mask is not None:
1592
+ mask = cv2.copyMakeBorder(
1593
+ mask, 0, 0, left_pad, right_pad, cv2.BORDER_CONSTANT, value=0
1594
+ )
1595
+ elif new_w > self.image_width:
1596
+ img = cv2.resize(img, (self.image_width, th))
1597
+ if mask is not None:
1598
+ mask = cv2.resize(mask, (self.image_width, th), interpolation=cv2.INTER_NEAREST)
1599
+
1600
+ return img, mask
1601
+
1602
+ @staticmethod
1603
+ def _estimate_bg(img: np.ndarray) -> int:
1604
+ """Estimate background color from border."""
1605
+ gray = cv2.cvtColor(img, cv2.COLOR_RGB2GRAY) if img.ndim == 3 else img
1606
+ border = np.concatenate((gray[0, :], gray[-1, :], gray[:, 0], gray[:, -1]))
1607
+ return int(np.median(border))