asterocr 1.0.0__py3-none-any.whl

asterocr/synthesizer/generator.py

@@ -0,0 +1,205 @@
+"""
+AsterOCR High-Performance Synthetic Text Image Generator
+Features:
+- Dynamically discovers and loads all Windows Vietnamese TTF/OTF fonts.
+- Multi-style background generation: aged yellow paper, scan paper, grid/notebook paper, white paper.
+- Real-world document degradations:
+  * Ink bleed / erosion / dilation
+  * Gaussian & defocus blur
+  * Salt-and-pepper / scanner noise
+  * Slight perspective / affine shear / rotation (-3 to +3 deg)
+  * Contrast & brightness variations
+- Directly outputs normalized (H=32, W) PIL Images for training.
+"""
+
+import os
+import sys
+import random
+import numpy as np
+
+if sys.platform == "win32":
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+        sys.stderr.reconfigure(encoding='utf-8')
+    except Exception:
+        pass
+
+# Ensure parent directory is in sys.path
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "../..")))
+from PIL import Image, ImageDraw, ImageFont, ImageFilter, ImageEnhance
+import cv2
+
+SYSTEM_FONT_DIR = "C:/Windows/Fonts"
+
+# Preferred fonts that render Vietnamese characters reliably
+PREFERRED_FONTS = [
+    "arial.ttf", "arialbd.ttf", "times.ttf", "timesbd.ttf", "tahoma.ttf",
+    "tahomabd.ttf", "calibri.ttf", "calibrib.ttf", "segoeui.ttf", "segoeuib.ttf",
+    "verdana.ttf", "verdanab.ttf", "cour.ttf", "courbd.ttf", "georgia.ttf",
+    "comic.ttf", "cambria.ttc"
+]
+
+class AsterTextGenerator:
+    def __init__(self, font_dir=SYSTEM_FONT_DIR):
+        self.font_paths = []
+        if os.path.exists(font_dir):
+            for fname in os.listdir(font_dir):
+                if fname.lower().endswith(('.ttf', '.otf', '.ttc')):
+                    full_p = os.path.join(font_dir, fname)
+                    self.font_paths.append(full_p)
+                    
+        # Filter for preferred fonts first
+        self.preferred_paths = [
+            os.path.join(font_dir, pf) for pf in PREFERRED_FONTS
+            if os.path.exists(os.path.join(font_dir, pf))
+        ]
+        if not self.preferred_paths:
+            self.preferred_paths = self.font_paths[:10] if self.font_paths else []
+
+    def get_random_font(self, size=24):
+        pool = self.preferred_paths if random.random() < 0.85 and self.preferred_paths else self.font_paths
+        if not pool:
+            return ImageFont.load_default()
+        font_p = random.choice(pool)
+        try:
+            return ImageFont.truetype(font_p, size)
+        except Exception:
+            try:
+                return ImageFont.truetype("arial.ttf", size)
+            except Exception:
+                return ImageFont.load_default()
+
+    def generate_background(self, width, height, style=None):
+        if style is None:
+            style = random.choices(["clean", "aged", "scan", "grid"], weights=[0.4, 0.3, 0.2, 0.1])[0]
+            
+        if style == "clean":
+            # White or near-white
+            bg_val = random.randint(240, 255)
+            img = Image.new("RGB", (width, height), (bg_val, bg_val, bg_val))
+            
+        elif style == "aged":
+            # Aged yellowish / brownish paper
+            r = random.randint(225, 248)
+            g = random.randint(r - 25, r - 5)
+            b = random.randint(g - 35, g - 15)
+            img = Image.new("RGB", (width, height), (r, g, b))
+            # Add slight gradient or texture
+            arr = np.array(img, dtype=np.int16)
+            noise = np.random.randint(-8, 8, (height, width, 3))
+            arr = np.clip(arr + noise, 0, 255).astype(np.uint8)
+            img = Image.fromarray(arr)
+            
+        elif style == "scan":
+            # Grayish scan document with paper grain
+            val = random.randint(215, 238)
+            img = Image.new("RGB", (width, height), (val, val, val))
+            arr = np.array(img, dtype=np.int16)
+            noise = np.random.normal(0, 4, (height, width, 3))
+            arr = np.clip(arr + noise, 0, 255).astype(np.uint8)
+            img = Image.fromarray(arr)
+            
+        else: # grid / lined
+            img = Image.new("RGB", (width, height), (250, 250, 252))
+            draw = ImageDraw.Draw(img)
+            # Faint horizontal or vertical line
+            line_y = random.randint(height // 2, height - 2)
+            draw.line([(0, line_y), (width, line_y)], fill=(210, 220, 235), width=1)
+            
+        return img
+
+    def render_text(self, text, target_height=32):
+        """Renders text into a normalized (H=target_height, W) PIL Image."""
+        if not text:
+            text = " "
+            
+        font_size = random.randint(20, 26)
+        font = self.get_random_font(font_size)
+        
+        # Measure text size
+        dummy = Image.new("RGB", (1, 1))
+        draw_dummy = ImageDraw.Draw(dummy)
+        bbox = draw_dummy.textbbox((0, 0), text, font=font)
+        t_w = max(10, bbox[2] - bbox[0])
+        t_h = max(10, bbox[3] - bbox[1])
+        
+        # Extra padding around text
+        pad_x = random.randint(6, 16)
+        pad_y = random.randint(4, 10)
+        canvas_w = t_w + pad_x * 2
+        canvas_h = t_h + pad_y * 2
+        
+        bg_img = self.generate_background(canvas_w, canvas_h)
+        draw = ImageDraw.Draw(bg_img)
+        
+        # Ink color: dark black, navy, faded ink, typewriter purple
+        ink_style = random.random()
+        if ink_style < 0.7:
+            # Black / dark charcoal
+            ink_val = random.randint(10, 45)
+            ink_color = (ink_val, ink_val, ink_val)
+        elif ink_style < 0.85:
+            # Blue ink (ballpoint pen)
+            ink_color = (random.randint(15, 35), random.randint(25, 55), random.randint(90, 150))
+        elif ink_style < 0.95:
+            # Faded printer ink
+            ink_val = random.randint(60, 95)
+            ink_color = (ink_val, ink_val, ink_val)
+        else:
+            # Stamp red
+            ink_color = (random.randint(140, 190), random.randint(25, 55), random.randint(25, 55))
+            
+        draw.text((pad_x - bbox[0], pad_y - bbox[1]), text, font=font, fill=ink_color)
+        
+        # Apply realistic augmentations
+        bg_img = self.apply_augmentations(bg_img)
+        
+        # Resize to fixed target_height (e.g. 32) preserving aspect ratio
+        w_orig, h_orig = bg_img.size
+        new_w = max(16, int((target_height / max(1, h_orig)) * w_orig))
+        final_img = bg_img.resize((new_w, target_height), Image.BILINEAR)
+        return final_img
+
+    def apply_augmentations(self, img):
+        # 1. Rotation (-2.5 to 2.5 degrees)
+        if random.random() < 0.4:
+            angle = random.uniform(-2.5, 2.5)
+            img = img.rotate(angle, resample=Image.BILINEAR, expand=True, fillcolor=(255, 255, 255))
+            
+        # 2. Gaussian Blur
+        if random.random() < 0.35:
+            radius = random.uniform(0.3, 0.9)
+            img = img.filter(ImageFilter.GaussianBlur(radius))
+            
+        # 3. Ink dilation / erosion with OpenCV
+        if random.random() < 0.25:
+            cv_img = np.array(img)
+            kernel_size = random.choice([2, 3])
+            kernel = np.ones((kernel_size, kernel_size), np.uint8)
+            if random.random() < 0.5:
+                cv_img = cv2.erode(cv_img, kernel, iterations=1) # thicker ink
+            else:
+                cv_img = cv2.dilate(cv_img, kernel, iterations=1) # thinner ink
+            img = Image.fromarray(cv_img)
+            
+        # 4. Brightness & Contrast Jitter
+        if random.random() < 0.4:
+            enh_b = ImageEnhance.Brightness(img)
+            img = enh_b.enhance(random.uniform(0.85, 1.15))
+        if random.random() < 0.4:
+            enh_c = ImageEnhance.Contrast(img)
+            img = enh_c.enhance(random.uniform(0.85, 1.25))
+            
+        return img
+
+default_generator = AsterTextGenerator()
+
+if __name__ == "__main__":
+    from asterocr.synthesizer.corpus import generate_random_corpus_text
+    os.makedirs("test_samples", exist_ok=True)
+    for i in range(5):
+        t = generate_random_corpus_text()
+        im = default_generator.render_text(t)
+        p = f"test_samples/sample_{i+1}.png"
+        im.save(p)
+        print(f"Generated: '{t}' -> saved to {p} (size: {im.size})")

asterocr/synthesizer/handwriting_generator.py

@@ -0,0 +1,420 @@
+"""
+AsterOCR Advanced Vietnamese Handwriting & Diverse Receipt Generator
+Produces realistic Vietnamese handwritten documents and thermal receipts/invoices.
+Features:
+- Notebook paper with school grid lines (ô ly học sinh) & horizontal lines
+- Realistic ink physics: ballpoint blue, gel black, pencil graphite, fountain pen
+- Handwriting dynamics: per-glyph baseline jitter, slant (±12 deg), variable pen pressure
+- Thermal receipts: dot-matrix look, store names, VAT, VND amounts, transaction codes
+- Multiprocessing-ready for millions of samples directly into LMDB
+"""
+
+import os
+import io
+import sys
+import math
+import random
+import time
+import numpy as np
+from PIL import Image, ImageDraw, ImageFont, ImageFilter, ImageOps
+import cv2
+
+if sys.platform == "win32":
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+        sys.stderr.reconfigure(encoding='utf-8')
+    except Exception:
+        pass
+
+from asterocr.synthesizer.font_manager import get_handwriting_fonts, get_receipt_fonts
+from asterocr.synthesizer.corpus import generate_random_corpus_text
+
+# Specialized corpus templates for handwriting, receipts, and forms
+HANDWRITTEN_TEMPLATES = [
+    "Tôi tên là {name}, sinh ngày {date}",
+    "Địa chỉ: {address}",
+    "Số điện thoại liên hệ: {phone}",
+    "Số CCCD: {cccd}, cấp ngày {date}",
+    "Kính gửi: Ban Giám hiệu Trường {school}",
+    "Em xin phép được nghỉ học ngày {date}",
+    "Cộng hòa Xã hội Chủ nghĩa Việt Nam",
+    "Độc lập - Tự do - Hạnh phúc",
+    "Đơn xin xác nhận tình trạng cư trú",
+    "Người làm đơn: {name}",
+    "Cam đoan lời khai trên là hoàn toàn đúng sự thật",
+    "Hà Nội, ngày {day} tháng {month} năm 2026",
+    "Hồ Chí Minh, ngày {day} tháng {month} năm 2026",
+    "Đà Nẵng, ngày {day} tháng {month} năm 2026",
+    "Bút bi xanh Thiên Long ngòi 0.5mm",
+    "Ghi chú: Đã thanh toán đầy đủ tiền cọc",
+    "Bài học số {num}: Lịch sử dựng nước và giữ nước",
+    "Văn mẫu lớp {num}: Miêu tả cảnh đẹp quê hương em",
+    "Tổng số tiền bằng chữ: {money_words}",
+]
+
+RECEIPT_TEMPLATES = [
+    "HÓA ĐƠN BÁN LẺ",
+    "PHIẾU THANH TOÁN",
+    "HÓA ĐƠN GIÁ TRỊ GIA TĂNG",
+    "SIÊU THỊ CO.OPMART HÀ NỘI",
+    "CỬA HÀNG TIỆN LỢI CIRCLE K",
+    "NHÀ THUỐC LONG CHÂU - CHI NHÁNH {num}",
+    "HIGHLANDS COFFEE - {address}",
+    "TRÀ SỮA PHÚC LONG TEA & COFFEE",
+    "BÁNH MÌ HUYNH HOA - SỐ LƯỢNG: {num}",
+    "Mã HĐ: HD{code}-{num}",
+    "Mã tra cứu: {code}VN",
+    "MST: 0{code}89",
+    "Ngày: {date} {time}",
+    "Thu ngân: NV_{name}",
+    "Cà phê sữa đá: {amount} đ",
+    "Trà sen vàng size L: {amount} đ",
+    "Bánh ngọt Tiramisu: {amount} VND",
+    "Cơm tấm sườn bì chả: {amount} đ",
+    "Phở bò tái nạm đặc biệt: {amount} đ",
+    "Tiền hàng: {amount} VND",
+    "Thuế VAT (8%): {amount} đ",
+    "TỔNG CỘNG: {amount} VNĐ",
+    "Tiền mặt: {amount} đ",
+    "Tiền thối lại: {amount} đ",
+    "Cảm ơn Quý khách - Hẹn gặp lại!",
+]
+
+NAMES = ["Nguyễn Văn An", "Trần Thị Mai", "Lê Hoàng Long", "Phạm Minh Đức", "Hoàng Thu Thảo", "Vũ Hải Đăng", "Đỗ Thanh Hằng", "Bùi Quốc Tuấn", "Đinh Ngọc Ánh", "Ngô Gia Bảo"]
+ADDRESSES = ["123 Phố Huế, Hai Bà Trưng, Hà Nội", "45 Lê Duẩn, P. Bến Nghé, Quận 1, TP.HCM", "78 Nguyễn Tri Phương, Thanh Khê, Đà Nẵng", "12 Hoàng Văn Thụ, Cần Thơ", "89 Trần Phú, Nha Trang, Khánh Hòa"]
+SCHOOLS = ["Tiểu học Thăng Long", "THCS Chu Văn An", "THPT Chuyên Hà Nội - Amsterdam", "Đại học Bách Khoa", "Đại học Quốc gia"]
+MONEY_WORDS = ["Một trăm năm mươi nghìn đồng chẵn", "Hai triệu ba trăm năm mươi nghìn đồng", "Năm mươi nghìn đồng", "Tám trăm chín mươi nghìn đồng"]
+
+def sample_handwritten_text():
+    """Generates realistic Vietnamese text for handwriting."""
+    r = random.random()
+    if r < 0.4:
+        tpl = random.choice(HANDWRITTEN_TEMPLATES)
+        text = tpl.format(
+            name=random.choice(NAMES),
+            date=f"{random.randint(1, 28):02d}/{random.randint(1, 12):02d}/{random.randint(1985, 2025)}",
+            address=random.choice(ADDRESSES),
+            phone=f"09{random.randint(10000000, 99999999)}",
+            cccd=f"001{random.randint(100000000, 999999999)}",
+            school=random.choice(SCHOOLS),
+            day=f"{random.randint(1, 28):02d}",
+            month=f"{random.randint(1, 12):02d}",
+            num=random.randint(1, 12),
+            money_words=random.choice(MONEY_WORDS)
+        )
+        return text
+    elif r < 0.8:
+        # Standard administrative / sentence text
+        return generate_random_corpus_text("sentence")
+    else:
+        # Complex diacritic-heavy combinations
+        return generate_random_corpus_text("administrative")
+
+def sample_receipt_text():
+    """Generates realistic Vietnamese receipt & thermal invoice text."""
+    r = random.random()
+    if r < 0.65:
+        tpl = random.choice(RECEIPT_TEMPLATES)
+        text = tpl.format(
+            name=random.choice(["Thu", "Nam", "Linh", "Hoa", "Tuấn", "Lan"]),
+            code=random.randint(10000, 99999),
+            num=random.randint(1, 99),
+            address=random.choice(["Hà Nội", "TP.HCM", "Đà Nẵng", "Cầu Giấy", "Quận 1"]),
+            date=f"{random.randint(1, 28):02d}/{random.randint(1, 12):02d}/2026",
+            time=f"{random.randint(7, 22):02d}:{random.randint(0, 59):02d}",
+            amount=f"{random.randint(15, 850) * 1000:,}".replace(",", ".")
+        )
+        return text
+    elif r < 0.85:
+        # Currency and item lines
+        return f"{random.choice(['Thanh toán', 'Tạm tính', 'Thành tiền', 'Chiết khấu'])}: {random.randint(10, 500) * 1000:,} đ".replace(",", ".")
+    else:
+        return generate_random_corpus_text("digits")
+
+class RealisticHandwritingRenderer:
+    """Renders authentic handwritten Vietnamese crops with pen physics and notebook paper."""
+    
+    def __init__(self):
+        self.fonts = get_handwriting_fonts()
+        if not self.fonts:
+            # Fallback
+            self.fonts = ["C:/Windows/Fonts/arial.ttf"]
+            
+        # Pen colors
+        self.ink_colors = [
+            (21, 48, 117),   # Ballpoint blue (classic)
+            (29, 78, 216),   # Bright royal blue
+            (14, 37, 94),    # Dark navy blue
+            (24, 24, 27),    # Gel black
+            (39, 39, 42),    # Charcoal black
+            (63, 63, 70),    # Pencil graphite
+            (88, 28, 135),   # Purple ink (school teacher / student)
+        ]
+        
+    def _create_notebook_paper(self, w, h):
+        """Creates realistic ruled notebook paper (ô ly học sinh or kẻ ngang)."""
+        # Base paper color: off-white, light cream, or gentle vintage
+        bg_r = random.randint(245, 255)
+        bg_g = random.randint(244, 253)
+        bg_b = random.randint(236, 248)
+        img = Image.new("RGB", (w, h), (bg_r, bg_g, bg_b))
+        draw = ImageDraw.Draw(img)
+        
+        style = random.choice(["ruled", "grid_oly", "plain", "dirty"])
+        
+        if style == "ruled":
+            # Horizontal notebook lines (blue or light purple)
+            line_y = int(h * random.uniform(0.72, 0.85))
+            line_col = random.choice([(199, 215, 245), (218, 210, 240), (200, 200, 200)])
+            draw.line([(0, line_y), (w, line_y)], fill=line_col, width=1)
+            # Maybe top secondary line
+            if random.random() < 0.5 and line_y - 20 > 0:
+                draw.line([(0, line_y - 20), (w, line_y - 20)], fill=line_col, width=1)
+                
+        elif style == "grid_oly":
+            # Ô ly học sinh (subtle blue/green grid lines)
+            grid_col = random.choice([(210, 230, 248), (220, 240, 230), (225, 225, 240)])
+            step_x = random.randint(18, 26)
+            for x in range(0, w, step_x):
+                draw.line([(x, 0), (x, h)], fill=grid_col, width=1)
+            step_y = random.randint(14, 20)
+            for y in range(0, h, step_y):
+                draw.line([(0, y), (w, y)], fill=grid_col, width=1)
+                
+        elif style == "dirty":
+            # Paper with subtle smudge or crease
+            arr = np.array(img, dtype=np.float32)
+            noise = np.random.normal(0, 3.0, (h, w, 3))
+            arr = np.clip(arr + noise, 0, 255).astype(np.uint8)
+            img = Image.fromarray(arr)
+            
+        return img
+
+    def render(self, text, target_height=32):
+        """Renders single handwriting crop with human dynamics."""
+        font_path = random.choice(self.fonts)
+        font_size = random.randint(22, 30)
+        try:
+            font = ImageFont.truetype(font_path, font_size)
+        except Exception:
+            font = ImageFont.load_default()
+            
+        ink = random.choice(self.ink_colors)
+        
+        # Calculate raw bounding box
+        dummy_img = Image.new("L", (1, 1))
+        draw_dummy = ImageDraw.Draw(dummy_img)
+        bbox = draw_dummy.textbbox((0, 0), text, font=font)
+        text_w = max(10, bbox[2] - bbox[0])
+        text_h = max(10, bbox[3] - bbox[1])
+        
+        # Canvas dimensions with padding for jitter & slanting
+        pad_x = random.randint(16, 32)
+        pad_y = random.randint(10, 20)
+        canvas_w = text_w + pad_x * 2
+        canvas_h = text_h + pad_y * 2
+        
+        # 1. Background
+        paper = self._create_notebook_paper(canvas_w, canvas_h)
+        
+        # 2. Text rendering with character-level baseline jitter
+        # To simulate human handwriting, render word-by-word with small y-jitter
+        words = text.split(" ")
+        curr_x = pad_x
+        draw = ImageDraw.Draw(paper)
+        
+        base_y = pad_y
+        for w_idx, word in enumerate(words):
+            # Baseline jitter (±2 px per word)
+            y_jitter = random.randint(-2, 2)
+            w_bbox = draw.textbbox((0, 0), word, font=font)
+            ww = w_bbox[2] - w_bbox[0]
+            
+            # Subtle ink variation per word
+            word_ink = (
+                int(np.clip(ink[0] + random.randint(-10, 10), 0, 255)),
+                int(np.clip(ink[1] + random.randint(-10, 10), 0, 255)),
+                int(np.clip(ink[2] + random.randint(-10, 10), 0, 255)),
+            )
+            draw.text((curr_x, base_y + y_jitter), word, fill=word_ink, font=font)
+            
+            # Space width
+            space_w = font_size // 3 + random.randint(-2, 4)
+            curr_x += ww + space_w
+            
+        # 3. Handwriting Slant & Shear
+        if random.random() < 0.7:
+            shear_factor = random.uniform(-0.22, 0.22) # natural slant
+            paper = paper.transform(
+                paper.size,
+                Image.AFFINE,
+                (1, shear_factor, 0, 0, 1, 0),
+                resample=Image.BICUBIC,
+                fillcolor=(250, 250, 250)
+            )
+            
+        # 4. Pen stroke dynamics: subtle ink bleed / paper absorption
+        if random.random() < 0.5:
+            paper = paper.filter(ImageFilter.GaussianBlur(radius=random.uniform(0.3, 0.6)))
+            
+        # 5. Crop tightly around text with pleasant margin
+        # Resize to target_height=32 preserving aspect ratio
+        w, h = paper.size
+        # Trim excess vertical padding
+        content_y1 = max(0, pad_y - 4)
+        content_y2 = min(h, pad_y + text_h + 8)
+        content_x1 = max(0, pad_x - 8)
+        content_x2 = min(w, curr_x + 8)
+        
+        if content_x2 > content_x1 and content_y2 > content_y1:
+            paper = paper.crop((content_x1, content_y1, content_x2, content_y2))
+            
+        pw, ph = paper.size
+        new_w = max(16, int((float(target_height) / max(1, ph)) * pw))
+        final_img = paper.resize((new_w, target_height), Image.LANCZOS)
+        
+        return final_img
+
+class RealisticReceiptRenderer:
+    """Renders authentic thermal paper receipts, dot-matrix invoices, vouchers."""
+    
+    def __init__(self):
+        self.fonts = get_receipt_fonts()
+        if not self.fonts:
+            self.fonts = ["C:/Windows/Fonts/consola.ttf"]
+            
+    def render(self, text, target_height=32):
+        """Renders single receipt line crop."""
+        font_path = random.choice(self.fonts)
+        font_size = random.randint(20, 26)
+        try:
+            font = ImageFont.truetype(font_path, font_size)
+        except Exception:
+            font = ImageFont.load_default()
+            
+        # Receipt paper colors: grayish white, slightly translucent thermal paper
+        bg_col = random.choice([
+            (248, 248, 248),
+            (242, 242, 242),
+            (238, 240, 242),
+            (252, 250, 245)
+        ])
+        
+        # Ink: black thermal print, sometimes faded purple/gray
+        ink_col = random.choice([
+            (25, 25, 25),
+            (45, 45, 45),
+            (60, 60, 65),     # Faded thermal print
+            (35, 40, 60),     # Dark blue-gray
+        ])
+        
+        dummy_img = Image.new("L", (1, 1))
+        draw_dummy = ImageDraw.Draw(dummy_img)
+        bbox = draw_dummy.textbbox((0, 0), text, font=font)
+        text_w = max(10, bbox[2] - bbox[0])
+        text_h = max(10, bbox[3] - bbox[1])
+        
+        pad_x = random.randint(8, 16)
+        pad_y = random.randint(6, 12)
+        canvas_w = text_w + pad_x * 2
+        canvas_h = text_h + pad_y * 2
+        
+        img = Image.new("RGB", (canvas_w, canvas_h), bg_col)
+        draw = ImageDraw.Draw(img)
+        
+        # Draw text
+        draw.text((pad_x, pad_y), text, fill=ink_col, font=font)
+        
+        # Thermal receipt imperfections:
+        # 1. Thermal print banding or fading
+        if random.random() < 0.4:
+            arr = np.array(img, dtype=np.float32)
+            fade_mask = np.linspace(random.uniform(0.85, 1.0), random.uniform(0.7, 0.95), canvas_w)
+            for c in range(3):
+                arr[:, :, c] = arr[:, :, c] * fade_mask[None, :] + 255 * (1 - fade_mask[None, :])
+            img = Image.fromarray(np.clip(arr, 0, 255).astype(np.uint8))
+            
+        # 2. Dot-matrix dithering or slight noise
+        if random.random() < 0.35:
+            arr = np.array(img, dtype=np.float32)
+            noise = np.random.normal(0, 4.0, (canvas_h, canvas_w, 3))
+            arr = np.clip(arr + noise, 0, 255).astype(np.uint8)
+            img = Image.fromarray(arr)
+            
+        # Resize to target_height=32
+        pw, ph = img.size
+        new_w = max(16, int((float(target_height) / max(1, ph)) * pw))
+        final_img = img.resize((new_w, target_height), Image.LANCZOS)
+        
+        return final_img
+
+# Module-level instances for fast reuse
+_hw_renderer = None
+_rc_renderer = None
+
+def get_renderers():
+    global _hw_renderer, _rc_renderer
+    if _hw_renderer is None:
+        _hw_renderer = RealisticHandwritingRenderer()
+    if _rc_renderer is None:
+        _rc_renderer = RealisticReceiptRenderer()
+    return _hw_renderer, _rc_renderer
+
+def synth_single_sample(mode="handwriting", target_height=32):
+    """
+    Generates a single synthetic sample (PIL.Image, text, source_type).
+    mode: 'handwriting' | 'receipt' | 'mixed'
+    """
+    hw_ren, rc_ren = get_renderers()
+    
+    if mode == "handwriting" or (mode == "mixed" and random.random() < 0.65):
+        text = sample_handwritten_text()
+        img = hw_ren.render(text, target_height=target_height)
+        source_type = "synth_handwriting"
+    else:
+        text = sample_receipt_text()
+        img = rc_ren.render(text, target_height=target_height)
+        source_type = "synth_receipt"
+        
+    return img, text, source_type
+
+def _worker_chunk_handwriting(args):
+    """Worker task function for multiprocessing pool."""
+    start_id, count, mode, target_height = args
+    hw_ren, rc_ren = get_renderers()
+    results = []
+    
+    for i in range(count):
+        sid = start_id + i
+        if mode == "handwriting" or (mode == "mixed" and random.random() < 0.65):
+            text = sample_handwritten_text()
+            img = hw_ren.render(text, target_height=target_height)
+            source_type = "synth_handwriting"
+        else:
+            text = sample_receipt_text()
+            img = rc_ren.render(text, target_height=target_height)
+            source_type = "synth_receipt"
+            
+        buf = io.BytesIO()
+        img.save(buf, format="JPEG", quality=random.randint(85, 95))
+        img_bytes = buf.getvalue()
+        results.append((sid, img_bytes, text, source_type))
+        
+    return results
+
+if __name__ == "__main__":
+    print("Test rendering 5 handwriting samples...")
+    hw, rc = get_renderers()
+    os.makedirs("test_samples", exist_ok=True)
+    for idx in range(5):
+        text = sample_handwritten_text()
+        img = hw.render(text)
+        img.save(f"test_samples/hw_{idx}.jpg")
+        print(f"  [HW {idx}] '{text}' -> {img.size}")
+        
+    for idx in range(5):
+        text = sample_receipt_text()
+        img = rc.render(text)
+        img.save(f"test_samples/rc_{idx}.jpg")
+        print(f"  [RC {idx}] '{text}' -> {img.size}")
+    print("[+] Test completed successfully! Samples saved in test_samples/")