Asyira / unified_pipeline /src /generator.py
asyirafitri's picture
Add unified_pipeline: merged signature-verification synthetic document generator (part 15)
65cc549 verified
Raw History Blame Contribute Delete
64.4 kB
"""Top-level orchestration: DatasetGenerator drives the full per-sample pipeline. For every sample this wires together, in order: 1. :class:`~src.templates.template_loader.TemplateLoader` -- pick a template + signature box. 2. :class:`~src.signatures.signature_dataset.SignatureDataset` -- pick a signature image. 3. :class:`~src.rendering.signature_preprocessor.SignaturePreprocessor` -- clean it into an RGBA stamp. 4. :class:`~src.placement.placement_engine.PlacementEngine` -- fit/rotate/position it. 5. :class:`~src.augmentation.augmentation_engine.AugmentationEngine` -- signature-layer effects. 6. :class:`~src.rendering.renderer.Renderer` -- blend onto the document. 7. :class:`~src.augmentation.augmentation_engine.AugmentationEngine` -- document-level effects. 8. :class:`~src.analysis.geometry_analyzer.GeometryAnalyzer` -- detect + measure. 9. :class:`~src.analysis.difficulty_analyzer.DifficultyAnalyzer` -- score. 10. :class:`~src.metadata.metadata_exporter.MetadataExporter` -- assemble + write JSON. 11. :class:`~src.analysis.validation_engine.ValidationEngine` -- verify. A single :class:`GeneratorContext` holds all stateless-between-calls engine instances for one process; :class:`DatasetGenerator` either drives it directly (``workers=1``) or fans it out across a :class:`concurrent.futures.ProcessPoolExecutor` pool, where each worker process builds exactly one context via ``_init_worker`` and reuses it for every sample it is assigned. Because every random draw is derived purely from ``(master_seed, sample_index, stage)``, results are identical regardless of worker count or scheduling order. """ from __future__ import annotations import csv import shutil from concurrent.futures import ProcessPoolExecutor, as_completed from dataclasses import dataclass from pathlib import Path from typing import Any import numpy as np from PIL import Image from tqdm import tqdm from src.analysis.difficulty_analyzer import DifficultyAnalyzer from src.analysis.geometry_analyzer import GeometryAnalyzer from src.analysis.validation_engine import ValidationEngine, ValidationReport, summarize from src.augmentation.augmentation_engine import AugmentationEngine from src.config.schema import DifficultyWeights, PipelineConfig, PlacementConfig, Range from src.cosmetics.cosmetic_fields import fill_all_cosmetic_fields from src.cosmetics.scanned_cosmetic_fields import fill_scanned_cosmetic_fields from src.metadata.metadata_exporter import MetadataExporter from src.placement.placement_engine import PlacementEngine, PlacementResult from src.rendering.printed_text import render_printed_name_stamp from src.rendering.renderer import Renderer from src.rendering.signature_preprocessor import SignaturePreprocessor from src.signatures.signature_dataset import SignatureDataset, SignatureRecord from src.templates.annotation_schema import SignatureBoxAnnotation, TemplatePageAnnotation from src.templates.procedural_template_provider import ProceduralTemplateProvider from src.templates.template_loader import Template, TemplateLoader from src.templates.template_provider import CompositeTemplateProvider, TemplateProvider, template_kind from src.utils.image_io import load_image_any, load_image_rgb, save_image_rgb from src.utils.logging_utils import get_logger from src.utils.names import generate_name, generate_role from src.utils.random_utils import SeedManager, resolve_scalar_or_range from src.verification.case_types import CASE_TABLE, CaseSpec from src.verification.registry import SignerIdentityRegistry from src.visualization.before_after_preview import save_before_after_preview from src.visualization.visualizer import save_visualization logger = get_logger(__name__) INK_COLOR_POOL: tuple[tuple[int, int, int], ...] = ( (15, 15, 20), # black (18, 22, 58), # blue-black (24, 34, 96), # ballpoint blue (12, 12, 14), # deep black ) # DifficultyWeights' schema defaults for these fields are the deck's # literal, generic reference constants (0.04 / 90 / 210 / 60) -- measured # (see configs/procedural_templates.yaml's own history) to peg smallness/ # faintness near their ceiling for almost any real signature on this # pipeline's own templates, especially procedural ones (real signature area # is ~0.2-1.5% of the page vs. the deck's assumed 4% "normal"). Previously # this recalibration only applied if the whole run used # `--config configs/procedural_templates.yaml`, which meant a # `template_provider: both` batch (or the plain CLI default) silently used # the deck-literal, too-aggressive constants for procedural samples anyway. # Applied automatically per-sample below, keyed on template_kind(), instead. # # faintness_dark_ref and low_texture_reference_stddev refit 2026-08-11 # against a fresh 60-sample natural draw of real procedural output # (mean_dark_intensity: p10=164.0/median=180.6/p90=195.7; gray_stddev: # p10=25.3/median=34.6/p90=46.5) -- the prior faintness_dark_ref (184) sat # ABOVE the real median (180.6), so `clamp01((dark_intensity-dark_ref)/...)` # floored to exactly 0.000 for every sample in a fresh measurement (20% of # the total score, contributing nothing, discriminating nothing, for the # entire procedural template family). Re-anchored to real p10 (~164, rounded # to 165) so faintness has genuine spread across the real distribution # instead of a constant zero: median sample now scores ~0.30, darkest # decile ~0, lightest observed (~208) ~0.79. low_texture_reference_stddev # was never split from the deck-literal default at all (only smallness/ # faintness were, historically) despite the same underlying asymmetry # existing here too -- anchored to real p90 (~46.5, rounded to 46) so the # best-textured decile of real samples can reach low_texture=0, the same # treatment already given to smallness_reference_area_ratio. _PROCEDURAL_DIFFICULTY_RECALIBRATION = { "smallness_reference_area_ratio": 0.003, "faintness_dark_ref": 165.0, "faintness_light_ref": 220.0, "low_texture_reference_stddev": 46.0, } # configs/default.yaml's own shipped baseline for placement.scale_factor -- # NOT the bare schema class default (a flat 0.9), the actual range every # real run resolves to unless a config/CLI override says otherwise. Used # below to detect "nobody customized this" without relying on # model_fields_set, which can't tell configs/default.yaml's own baseline # apart from a genuine user override (both look identical once merged). _DEFAULT_SCALE_FACTOR = Range(min=0.78, max=0.95) # scale_factor=1.15 (flat), not the ~0.78-0.95 shipped range -- procedural's # boxes (200x80px) have real headroom scanned's cramped real "sign here" # lines don't, measured 2026-08-11 across 20 real placements per candidate: # scale_factor=1.1 already gave a meaningful legibility gain (opaque-ink # fraction 0.238 -> 0.280) with ZERO overflow (median and p90 both 0%); 1.3 # starts trading further gains for real overflow (6-7%). 1.15 sits just past # the confirmed free win. Scanned was tested too (0.9 through 1.2) and # showed NO change at all in that range -- `min_signature_height_px` (see # PlacementConfig), not scale_factor, is the binding constraint there, so # scanned keeps configs/default.yaml's own range unchanged. _PROCEDURAL_PLACEMENT_RECALIBRATION = { "scale_factor": 1.15, } # perspective/page_tilt/crumple spatially warp the whole page, which used # to force baseline-diff ink detection to be skipped entirely for any # sample where one fired (a pixel in the final image no longer sat at the # same (x, y) it occupied in the clean baseline, so a naive diff would # compare misaligned pixels) -- this silently let large blocks of printed # text get misdetected as "ink" whenever a search box's expanded region # rotated/warped into them, corrupting difficulty scores for those samples. # Fixed for the SCORED target box: AugmentationEngine.apply_to_document()'s # optional `baseline_image` param now applies the exact same geometric # transform to a baseline companion image too, so the `warped_baseline` used # below stays pixel-aligned with `final_image` even after a transform -- # baseline exclusion no longer needs to be skipped there. This constant is # still used by compute_extra_signature_overlays() below, which re-detects # OTHER (non-scored, preview-only) boxes after generation already finished # and doesn't have a correspondingly-warped baseline on hand -- skipping # baseline exclusion for those is an accepted, lower-stakes fallback since # they never feed difficulty/verdict, only the before/after preview image. _GEOMETRIC_DOCUMENT_EFFECTS = ("perspective", "page_tilt", "crumple") @dataclass class SampleOutcome: """Lightweight, picklable result of generating one sample (used across process boundaries).""" sample_id: str success: bool error: "str | None" = None difficulty_tier: "str | None" = None difficulty_score: "float | None" = None validation_passed: "bool | None" = None validation_errors: int = 0 validation_warnings: int = 0 # Populated on success -- feeds dataset_summary.csv (see DatasetGenerator.generate()). case_folder: "str | None" = None template_id: "str | None" = None template_kind: "str | None" = None case_type: "str | None" = None verdict: "str | None" = None reject_code: "str | None" = None signer_name: "str | None" = None class GeneratorContext: """Holds every stateless-between-calls engine instance needed to generate a sample.""" def __init__(self, config: PipelineConfig) -> None: self.config = config self.template_provider = self._build_template_provider(config) self.signature_dataset = SignatureDataset( config.paths.dataset_dir, signet_dir=config.paths.signet_dir, gpds_dir=config.paths.gpds_dir, bhsig260_hindi_dir=config.paths.bhsig260_hindi_dir, bhsig260_bengali_dir=config.paths.bhsig260_bengali_dir, ) self.preprocessor = SignaturePreprocessor() self.placement_engine = PlacementEngine(config.placement) self._placement_engine_procedural = self._build_procedural_placement_engine(config.placement) self.augmentation_engine = AugmentationEngine(config.augmentation) self.renderer = Renderer(config.rendering) self.geometry_analyzer = GeometryAnalyzer() self.difficulty_analyzer = DifficultyAnalyzer(config.difficulty) self._difficulty_analyzer_procedural = self._build_procedural_difficulty_analyzer(config.difficulty) self.metadata_exporter = MetadataExporter() self.validation_engine = ValidationEngine(config.validation, config.difficulty) # Trigger discovery eagerly so the first sample doesn't pay (and doesn't # race another worker on) the filesystem-scan + annotation-cache cost. self.template_provider.discover() self.signature_dataset.discover() self.identity_registry = SignerIdentityRegistry(self.template_provider, self.signature_dataset, config.seed) # Set by _run_generic_sample/_run_case_sample on every call: the # document right after signature placement, before document-level # augmentation. run_sample()'s return signature is unchanged (still # just metadata/image/report, matching every existing caller), so # this is how the "before" image for save_before_after_preview # escapes to _generate_and_export without a breaking API change. # One GeneratorContext is used sequentially within a single worker # process/sample at a time (see DatasetGenerator/_init_worker), so # this is safe -- it always reflects the most recent run_sample() # call by the time that call returns. self.last_clean_image: "np.ndarray | None" = None # Set alongside last_clean_image, same call sites, same lifetime # caveat -- lets a caller (e.g. streamlit_app.py's interactive # degradation lever) re-run GeometryAnalyzer/DifficultyAnalyzer on a # hypothetically-more-or-less-degraded version of last_clean_image # and get a live difficulty score, the same way the real # generation pipeline would have scored it. self.last_baseline_image: "np.ndarray | None" = None self.last_target_box: "tuple[float, float, float, float] | None" = None self.last_canvas_size: "tuple[int, int] | None" = None @staticmethod def _build_procedural_difficulty_analyzer(base_weights: DifficultyWeights) -> DifficultyAnalyzer: """A second :class:`DifficultyAnalyzer`, sharing every field of ``base_weights`` except the 3 smallness/faintness reference constants -- used only for procedural-template samples (see :meth:`_difficulty_analyzer_for`). If the caller already explicitly set any of those 3 fields (a CLI ``--set difficulty....=`` override, or a whole config profile like ``configs/procedural_templates.yaml`` that sets them itself), that choice is respected as-is and applied to every sample regardless of template kind -- explicit configuration always wins over this automatic per-kind default. """ explicitly_set = base_weights.model_fields_set overrides = { key: value for key, value in _PROCEDURAL_DIFFICULTY_RECALIBRATION.items() if key not in explicitly_set } if not overrides: return DifficultyAnalyzer(base_weights) return DifficultyAnalyzer(base_weights.model_copy(update=overrides)) def _difficulty_analyzer_for(self, template_id: str) -> DifficultyAnalyzer: """Picks the deck-literal or procedural-recalibrated analyzer for this sample's template -- keyed per-sample (not per-run), so a ``template_provider: both`` batch scores each sample against the constants that actually fit its template family, instead of one global setting silently misgrading half the batch.""" if template_kind(template_id) == "procedural": return self._difficulty_analyzer_procedural return self.difficulty_analyzer @staticmethod def _build_procedural_placement_engine(base_placement: PlacementConfig) -> PlacementEngine: """A second :class:`PlacementEngine`, sharing every field of ``base_placement`` except ``scale_factor`` -- used only for procedural-template samples (see :meth:`_placement_engine_for`). Deliberately does NOT use ``model_fields_set`` the way :meth:`_build_procedural_difficulty_analyzer` does: unlike the difficulty reference constants (never set by ``configs/default.yaml``, so ``model_fields_set`` cleanly means "a real user override"), ``configs/default.yaml`` itself always sets ``placement.scale_factor`` (to its own natural-variation range, ``{min: 0.78, max: 0.95}``) -- so ``model_fields_set`` would always contain ``scale_factor`` on every run, silently defeating this recalibration 100% of the time regardless of whether a real user override exists. Compares the RESOLVED value against that known shipped baseline instead: matches it -> safe to recalibrate; differs (a real ``--set``/custom-profile override) -> respected as-is for every template, same intent as the difficulty version. """ if base_placement.scale_factor == _DEFAULT_SCALE_FACTOR: return PlacementEngine(base_placement.model_copy(update=_PROCEDURAL_PLACEMENT_RECALIBRATION)) return PlacementEngine(base_placement) def _placement_engine_for(self, template_id: str) -> PlacementEngine: """Picks the base or procedural-recalibrated placement engine for this sample's template -- same per-sample keying as :meth:`_difficulty_analyzer_for`, for the same reason (a ``template_provider: both`` batch shouldn't apply one family's placement tuning to the other's templates).""" if template_kind(template_id) == "procedural": return self._placement_engine_procedural return self.placement_engine @staticmethod def _build_template_provider(config: PipelineConfig) -> "TemplateProvider": """Builds the configured template source(s) -- see ``paths.template_provider`` in ``src/config/schema.py``. ``TemplateLoader`` (scanned) and ``ProceduralTemplateProvider`` are structurally interchangeable (:class:`~src.templates.template_provider.TemplateProvider`); "both" merges their id spaces via :class:`CompositeTemplateProvider`. """ kind = config.paths.template_provider excluded = frozenset(config.paths.excluded_template_ids) if kind == "scanned": return TemplateLoader(config.paths.image_dir, config.paths.annotations_dir, excluded_ids=excluded) if kind == "procedural": return ProceduralTemplateProvider(config.paths.cache_dir) scanned = TemplateLoader(config.paths.image_dir, config.paths.annotations_dir, excluded_ids=excluded) procedural = ProceduralTemplateProvider(config.paths.cache_dir) return CompositeTemplateProvider([scanned, procedural]) def run_sample( self, sample_index: int, seed_suffix: "str | None" = None, ) -> tuple[dict[str, Any], "np.ndarray", "ValidationReport | None"]: """Generate one sample. Args: sample_index: Used for both the output filename (``case_NNNNNN``) and, when ``seed_suffix`` is ``None``, the seed itself. seed_suffix: When given, the seed is derived from ``f"{sample_index}_{seed_suffix}"`` instead of the bare index -- a different, still-fully-deterministic draw for the same nominal sample, used by :meth:`run_sample_targeting_difficulty`'s retry loop so a retry doesn't just reproduce the exact same result. """ cfg = self.config seed_key = sample_index if seed_suffix is None else f"{sample_index}_{seed_suffix}" sm = SeedManager(cfg.seed, seed_key) prefix = cfg.generation.filename_prefix digits = cfg.generation.filename_digits sample_id = f"{prefix}_{sample_index:0{digits}d}" case_spec = CASE_TABLE.get(cfg.quality.case_type) if case_spec is not None: return self._run_case_sample(sample_id, sm, case_spec) return self._run_generic_sample(sample_id, sm) def run_sample_targeting_difficulty( self, sample_index: int, target_score: float, tolerance: float = 0.05, max_attempts: int = 5, ) -> tuple[dict[str, Any], "np.ndarray", "ValidationReport | None"]: """Generate a sample whose ``difficulty.score`` lands within ``tolerance`` of ``target_score``, retrying with fresh (but still deterministic) randomness up to ``max_attempts`` times. Ported from projectA's ``cli.py --difficulty {easy,medium,hard}`` retry-loop (``case_generation.py::generate_case_at_difficulty()``), generalized from a coarse tier request to this pipeline's own continuous ``[0, 1]`` score -- request ``0.55``, not ``"medium"``. Every attempt is still fully reproducible from ``(seed, sample_index, attempt)``; the closest-scoring attempt is kept even if none lands within tolerance (metadata's ``difficulty_targeting`` block records whether it actually matched). """ # Tracks last_clean_image alongside each attempt's result -- it's # otherwise only ever set to the MOST RECENT run_sample() call # (see the attribute's docstring in __init__), which would silently # mismatch the returned metadata/image whenever the winning attempt # (best-so-far, or the final match) isn't the last one tried. best: "tuple[dict, np.ndarray, ValidationReport | None, float, np.ndarray | None, np.ndarray | None, tuple | None, tuple | None] | None" = None for attempt in range(max_attempts): suffix = None if attempt == 0 else f"difficulty_retry{attempt}" metadata, image, report = self.run_sample(sample_index, seed_suffix=suffix) score = metadata["difficulty"]["score"] delta = abs(score - target_score) if best is None or delta < best[3]: best = ( metadata, image, report, delta, self.last_clean_image, self.last_baseline_image, self.last_target_box, self.last_canvas_size, ) if delta <= tolerance: metadata["difficulty_targeting"] = { "requested_score": target_score, "tolerance": tolerance, "attempts_used": attempt + 1, "matched": True, } return metadata, image, report metadata, image, report, delta, clean_image, baseline_image, target_box, canvas_size = best self.last_clean_image = clean_image self.last_baseline_image = baseline_image self.last_target_box = target_box self.last_canvas_size = canvas_size metadata["difficulty_targeting"] = { "requested_score": target_score, "tolerance": tolerance, "attempts_used": max_attempts, "matched": False, } logger.warning( "Sample %d: could not reach difficulty %.3f (+/-%.3f) in %d attempts; closest was %.3f (delta=%.3f).", sample_index, target_score, tolerance, max_attempts, metadata["difficulty"]["score"], delta, ) return metadata, image, report def _run_generic_sample(self, sample_id: str, sm: SeedManager) -> tuple[dict[str, Any], "np.ndarray", "ValidationReport | None"]: cfg = self.config template = self._select_template(sm) page_annotation = self._select_page(template) box = self._select_box(page_annotation, sm) document_image = load_image_rgb(template.image_path) baseline_image = document_image # pristine, pre-cosmetic-fields/pre-signature -- see analyze()'s baseline_image_rgb canvas_h, canvas_w = document_image.shape[:2] target_box = box.as_tuple() signer_name = cfg.signer.name or generate_name(sm.python_rng("signer_name")) signer_role = cfg.signer.role or box.role or generate_role(sm.python_rng("signer_role")) document_image, cosmetic_field_boxes = self._maybe_fill_cosmetic_fields(document_image, template, page_annotation, box.id, signer_name, sm) signature_record = self._select_signature(sm) raw_signature = load_image_any(signature_record.path) ink_color = INK_COLOR_POOL[int(sm.numpy_rng("ink_color").integers(0, len(INK_COLOR_POOL)))] signature_rgba = self.preprocessor.process(raw_signature, ink_color=ink_color) placement = self._placement_engine_for(template.template_id).place( signature_rgba, target_box=target_box, canvas_size=(canvas_w, canvas_h), seed_manager=sm, ) signature_layer, signature_aug_records = self.augmentation_engine.apply_to_signature(placement.layer, sm) render_result = self.renderer.blend(document_image, signature_layer, sm) # If this template has more than one signature box, fill every # OTHER box with its own genuine signature too -- a "generic" # (non-case-type) sample is meant to represent a normal, properly # executed document, so leaving a second box conspicuously blank # looked like a broken render rather than a deliberate test case. # Only quality.case_type-driven samples (via _run_case_sample, # e.g. 5a/5b) are meant to leave a box blank/wrong, each with its # own labeled verdict/reject_code explaining why. These extra # signatures aren't scored (geometry/difficulty stay keyed to the # single primary `box` selected above, matching the rest of this # method's schema), just rendered -- recorded under # metadata["additional_signatures"] for traceability. other_boxes = [b for b in page_annotation.signature_boxes if b.id != box.id] additional_signatures: "list[dict] | None" = None document_with_all_signatures = render_result.image if other_boxes: additional_signatures = [] for other_box in other_boxes: sm_other = SeedManager(cfg.seed, f"{sm.sample_index}_box_{other_box.id}") other_record = self._select_signature(sm_other) other_raw = load_image_any(other_record.path) other_ink_color = INK_COLOR_POOL[int(sm_other.numpy_rng("ink_color").integers(0, len(INK_COLOR_POOL)))] other_rgba = self.preprocessor.process(other_raw, ink_color=other_ink_color) other_placement = self._placement_engine_for(template.template_id).place( other_rgba, target_box=other_box.as_tuple(), canvas_size=(canvas_w, canvas_h), seed_manager=sm_other, ) other_layer, _ = self.augmentation_engine.apply_to_signature(other_placement.layer, sm_other) other_render = self.renderer.blend(document_with_all_signatures, other_layer, sm_other) document_with_all_signatures = other_render.image other_name = self.identity_registry.display_name(other_record.signer_group) document_with_all_signatures, other_field_boxes = self._fill_box_cosmetic_field( document_with_all_signatures, template, page_annotation, other_box.id, other_name, sm_other, ) if other_field_boxes: cosmetic_field_boxes = {**(cosmetic_field_boxes or {}), **other_field_boxes} additional_signatures.append({ "box_id": other_box.id, "role": other_box.role, "signature_id": other_record.signature_id, "signer_group": other_record.signer_group, "source_type": other_record.source_type, "script": other_record.script, "ref_path": other_record.path.as_posix(), }) self.last_clean_image = document_with_all_signatures.copy() self.last_baseline_image = baseline_image self.last_target_box = target_box self.last_canvas_size = (canvas_w, canvas_h) final_image, document_aug_records, warped_baseline = self.augmentation_engine.apply_to_document( document_with_all_signatures, sm, baseline_image=baseline_image, ) geometry = self.geometry_analyzer.analyze( final_image, target_box=target_box, canvas_size=(canvas_w, canvas_h), placement_hint_bbox=placement.intended_bbox, baseline_image_rgb=warped_baseline, ) difficulty = self._difficulty_analyzer_for(template.template_id).analyze(geometry) quality_rng = sm.numpy_rng("quality") quality_values = { "scanner_quality": round(resolve_scalar_or_range(cfg.quality.scanner_quality, quality_rng), 4), "paper_quality": round(resolve_scalar_or_range(cfg.quality.paper_quality, quality_rng), 4), "render_quality": round(resolve_scalar_or_range(cfg.quality.render_quality, quality_rng), 4), } metadata = self.metadata_exporter.build( document_id=sample_id, template_id=template.template_id, document_type=template.annotation.document_type, page=page_annotation.page, page_size=(canvas_w, canvas_h), dpi=page_annotation.dpi, signer_name=signer_name, signer_role=signer_role, signature_source=signature_record, placement=placement, render=render_result, signature_aug=signature_aug_records, document_aug=document_aug_records, geometry=geometry, difficulty=difficulty, quality_cfg=cfg.quality, quality_values=quality_values, seed=cfg.seed, sample_index=sm.sample_index, verification=None, ) if cosmetic_field_boxes: metadata["cosmetics"] = {"field_boxes": cosmetic_field_boxes} if additional_signatures: metadata["additional_signatures"] = additional_signatures validation_report = None if cfg.generation.run_validation: validation_report = self.validation_engine.validate(metadata) return metadata, final_image, validation_report # ------------------------------------------------------------------ # # Verification test-case generation (case_type-driven) # ------------------------------------------------------------------ # def _run_case_sample( self, sample_id: str, sm: SeedManager, case_spec: CaseSpec, ) -> tuple[dict[str, Any], "np.ndarray", "ValidationReport | None"]: cfg = self.config template = self._select_template_for_case(sm, case_spec) page_annotation = self._select_page(template) boxes = page_annotation.signature_boxes if not boxes: raise ValueError(f"Page {page_annotation.page} has no signature boxes defined.") target_box, companion_box = self._select_case_boxes(boxes, sm) document_image = load_image_rgb(template.image_path) baseline_image = document_image # pristine, pre-cosmetic-fields/pre-signature -- see analyze()'s baseline_image_rgb canvas_h, canvas_w = document_image.shape[:2] target_box_tuple = target_box.as_tuple() canvas_size = (canvas_w, canvas_h) expected_group = self.identity_registry.authorized_signer_group(template.template_id, target_box.id) signer_name = cfg.signer.name or self.identity_registry.display_name(expected_group) signer_role = cfg.signer.role or target_box.role document_image, cosmetic_field_boxes = self._maybe_fill_cosmetic_fields(document_image, template, page_annotation, target_box.id, signer_name, sm) ink_color = INK_COLOR_POOL[int(sm.numpy_rng("ink_color").integers(0, len(INK_COLOR_POOL)))] document_after_companion = document_image companion_info: "dict[str, Any] | None" = None additional_signatures: "list[dict] | None" = None if case_spec.fill_companion: if companion_box is None: logger.warning( "Case %s wants a companion signer but template %s has only one signature box; skipping.", case_spec.code, template.template_id, ) else: companion_group = self.identity_registry.authorized_signer_group(template.template_id, companion_box.id) sm_companion = SeedManager(cfg.seed, f"{sm.sample_index}_companion") companion_record = self.signature_dataset.sample_from_group( sm_companion.numpy_rng("case:companion_signature"), companion_group, source_filter="genuine", ) companion_raw = load_image_any(companion_record.path) companion_rgba = self.preprocessor.process(companion_raw, ink_color=ink_color) companion_placement = self._placement_engine_for(template.template_id).place( companion_rgba, target_box=companion_box.as_tuple(), canvas_size=canvas_size, seed_manager=sm_companion, ) companion_layer, _ = self.augmentation_engine.apply_to_signature(companion_placement.layer, sm_companion) companion_render = self.renderer.blend(document_after_companion, companion_layer, sm_companion) document_after_companion = companion_render.image companion_name = self.identity_registry.display_name(companion_group) document_after_companion, companion_field_boxes = self._fill_box_cosmetic_field( document_after_companion, template, page_annotation, companion_box.id, companion_name, sm_companion, ) if companion_field_boxes: cosmetic_field_boxes = {**(cosmetic_field_boxes or {}), **companion_field_boxes} companion_info = { "box_id": companion_box.id, "filled": True, "signer_group": companion_group, "script": self.identity_registry.script_for(companion_group), "matches_expected": True, "ref_path": str(companion_record.path), } elif companion_box is not None: # This case type doesn't officially test a second signer (e.g. # 1a/1b/1d/2a/2b/3a/3b -- fill_companion=False), but the # template it landed on still has a second signature box. Fill # it correctly anyway, same reasoning as the generic-sample # path (_run_generic_sample): a properly executed document # shouldn't have a conspicuously blank second box with no # verdict/reject_code explaining why -- only fill_companion=True # types (5a/5b) are meant to leave a required box blank/wrong, # each with its own labeled verdict. Tracked separately from # `companion_info`/`verification.companion` (which describes # this case type's OWN tested companion behavior) under the # same "additional_signatures" key the generic path uses. extra_group = self.identity_registry.authorized_signer_group(template.template_id, companion_box.id) sm_extra = SeedManager(cfg.seed, f"{sm.sample_index}_extra_{companion_box.id}") extra_record = self.signature_dataset.sample_from_group( sm_extra.numpy_rng("case:extra_signature"), extra_group, source_filter="genuine", ) extra_raw = load_image_any(extra_record.path) extra_rgba = self.preprocessor.process(extra_raw, ink_color=ink_color) extra_placement = self._placement_engine_for(template.template_id).place( extra_rgba, target_box=companion_box.as_tuple(), canvas_size=canvas_size, seed_manager=sm_extra, ) extra_layer, _ = self.augmentation_engine.apply_to_signature(extra_placement.layer, sm_extra) extra_render = self.renderer.blend(document_after_companion, extra_layer, sm_extra) document_after_companion = extra_render.image extra_name = self.identity_registry.display_name(extra_group) document_after_companion, extra_field_boxes = self._fill_box_cosmetic_field( document_after_companion, template, page_annotation, companion_box.id, extra_name, sm_extra, ) if extra_field_boxes: cosmetic_field_boxes = {**(cosmetic_field_boxes or {}), **extra_field_boxes} additional_signatures = [{ "box_id": companion_box.id, "role": companion_box.role, "signature_id": extra_record.signature_id, "signer_group": extra_group, "source_type": extra_record.source_type, "script": self.identity_registry.script_for(extra_group), "ref_path": extra_record.path.as_posix(), }] actual_record, actual_group, actual_source_type, target_rgba = self._resolve_case_signature( case_spec, template, target_box, companion_box, expected_group, signer_name, ink_color, sm, ) if target_rgba is None: placement = PlacementResult( layer=np.zeros((canvas_h, canvas_w, 4), dtype=np.uint8), target_box=target_box_tuple, intended_bbox=target_box_tuple, x_offset=0.0, y_offset=0.0, rotation_deg=0.0, scale_factor=0.0, anchor_point=cfg.placement.anchor_point, misplaced=False, misplacement_dx=0.0, misplacement_dy=0.0, ) else: placement = self._placement_engine_for(template.template_id).place( target_rgba, target_box=target_box_tuple, canvas_size=canvas_size, seed_manager=sm, ) signature_layer, signature_aug_records = self.augmentation_engine.apply_to_signature(placement.layer, sm) render_result = self.renderer.blend(document_after_companion, signature_layer, sm) self.last_clean_image = render_result.image.copy() self.last_baseline_image = baseline_image self.last_target_box = target_box_tuple self.last_canvas_size = canvas_size final_image, document_aug_records, warped_baseline = self.augmentation_engine.apply_to_document( render_result.image, sm, baseline_image=baseline_image, ) geometry = self.geometry_analyzer.analyze( final_image, target_box=target_box_tuple, canvas_size=canvas_size, placement_hint_bbox=placement.intended_bbox, baseline_image_rgb=warped_baseline, expect_blank=target_rgba is None, ) difficulty = self._difficulty_analyzer_for(template.template_id).analyze(geometry) quality_rng = sm.numpy_rng("quality") quality_values = { "scanner_quality": round(resolve_scalar_or_range(cfg.quality.scanner_quality, quality_rng), 4), "paper_quality": round(resolve_scalar_or_range(cfg.quality.paper_quality, quality_rng), 4), "render_quality": round(resolve_scalar_or_range(cfg.quality.render_quality, quality_rng), 4), } verification_record = { "case_type": case_spec.code, "verdict": case_spec.verdict, "reject_code": case_spec.reject_code, "target_box_id": target_box.id, "expected_signer_group": expected_group, "expected_signer_script": self.identity_registry.script_for(expected_group), "actual_signer_group": actual_group, "actual_source_type": actual_source_type, "actual_signer_script": self.identity_registry.script_for(actual_group) if actual_group else None, "companion": companion_info, } metadata = self.metadata_exporter.build( document_id=sample_id, template_id=template.template_id, document_type=template.annotation.document_type, page=page_annotation.page, page_size=(canvas_w, canvas_h), dpi=page_annotation.dpi, signer_name=signer_name, signer_role=signer_role, signature_source=actual_record, placement=placement, render=render_result, signature_aug=signature_aug_records, document_aug=document_aug_records, geometry=geometry, difficulty=difficulty, quality_cfg=cfg.quality, quality_values=quality_values, seed=cfg.seed, sample_index=sm.sample_index, verification=verification_record, ) if cosmetic_field_boxes: metadata["cosmetics"] = {"field_boxes": cosmetic_field_boxes} if additional_signatures: metadata["additional_signatures"] = additional_signatures validation_report = None if cfg.generation.run_validation: validation_report = self.validation_engine.validate(metadata) return metadata, final_image, validation_report def _maybe_fill_cosmetic_fields( self, document_image: "np.ndarray", template: Template, page_annotation: TemplatePageAnnotation, primary_box_id: str, signer_name: str, sm: SeedManager, ) -> "tuple[np.ndarray, dict | None]": """Fills non-scored cosmetic fields if enabled -- SWIFT/NRIC/UEN/amounts on procedural templates (full field set, exact coordinates known from the drawing spec -- see :mod:`src.cosmetics.cosmetic_fields`), or a pre-measured name/company-name on scanned templates (coordinates cached in the template's own annotation file -- see :mod:`src.cosmetics.scanned_cosmetic_fields` and ``scripts/detect_cosmetic_field_coordinates.py`` for how they were measured -- and the 2 of 9 scanned templates that are stock photos with no genuine blank field to fill, which just have no ``cosmetic_fields`` entries). No-op (image unchanged, ``None`` boxes) when disabled, or when a scanned template has none configured. Only fills fields with no ``box_id`` (entity-level, e.g. ``company_name``) or tied to ``primary_box_id`` -- on a multi-signature-box template, a field belonging to a DIFFERENT box (e.g. a companion signatory's own "Print Name:" line) is filled separately once that signer's identity is known, by :meth:`_fill_box_cosmetic_field`. This method runs early, before any companion/additional signer is resolved, so it can only ever speak for the box it's actually given. """ if not self.config.document.enable_cosmetic_fields: return document_image, None if template_kind(template.template_id) == "scanned": fields = [f for f in page_annotation.cosmetic_fields if f.box_id in (None, primary_box_id)] image, boxes = fill_scanned_cosmetic_fields( document_image, fields, signer_name, sm.python_rng("cosmetic_fields"), ) return image, (boxes or None) field_boxes_fn = getattr(self.template_provider, "field_boxes_for", None) if field_boxes_fn is None: return document_image, None template_cfg = field_boxes_fn(template.template_id) if template_cfg is None: return document_image, None return fill_all_cosmetic_fields(document_image, template_cfg, signer_name, sm.python_rng("cosmetic_fields")) def _fill_box_cosmetic_field( self, document_image: "np.ndarray", template: Template, page_annotation: TemplatePageAnnotation, box_id: str, name: str, sm: SeedManager, ) -> "tuple[np.ndarray, dict | None]": """Second, later pass for a companion/additional signature box's own cosmetic field (e.g. bank_doc_04's LENDER "Print Name:" line, distinct from the BORROWER field :meth:`_maybe_fill_cosmetic_fields` already handled) -- called once that box's actual signer identity is known, which is always *after* the first pass already ran (see ``_run_case_sample``/``_run_generic_sample``). No-op if cosmetic fields are disabled, the template is procedural (no box-tied fields exist there), or this particular box has no such field (true for most single-name-field scanned templates). """ if not self.config.document.enable_cosmetic_fields or template_kind(template.template_id) != "scanned": return document_image, None fields = [f for f in page_annotation.cosmetic_fields if f.box_id == box_id] if not fields: return document_image, None image, boxes = fill_scanned_cosmetic_fields(document_image, fields, name, sm.python_rng("cosmetic_fields")) return image, (boxes or None) def _select_template_for_case(self, sm: SeedManager, case_spec: CaseSpec) -> Template: cfg = self.config if cfg.document.template: return self.template_provider.get(cfg.document.template) templates = self.template_provider.discover() if case_spec.fill_companion: candidates = sorted( tid for tid, t in templates.items() if len(t.annotation.pages[0].signature_boxes) >= 2 ) if not candidates: logger.warning( "Case %s needs a multi-box template but none were found; using the full template pool.", case_spec.code, ) candidates = sorted(templates.keys()) else: candidates = sorted(templates.keys()) idx = int(sm.numpy_rng("template_selection").integers(0, len(candidates))) return self.template_provider.get(candidates[idx]) def _select_case_boxes( self, boxes: "list[SignatureBoxAnnotation]", sm: SeedManager, ) -> "tuple[SignatureBoxAnnotation, SignatureBoxAnnotation | None]": idx = int(sm.numpy_rng("box_selection").integers(0, len(boxes))) target = boxes[idx] others = [b for i, b in enumerate(boxes) if i != idx] companion = others[0] if others else None return target, companion def _resolve_case_signature( self, case_spec: CaseSpec, template: Template, target_box: "SignatureBoxAnnotation", companion_box: "SignatureBoxAnnotation | None", expected_group: str, expected_name: str, ink_color: tuple[int, int, int], sm: SeedManager, ) -> "tuple[SignatureRecord | None, str | None, str, np.ndarray | None]": """Resolve what actually goes in the target box for one case type. Returns ``(signature_record_or_none, actual_signer_group_or_none, actual_source_type, rgba_layer_or_none)``. """ mode = case_spec.signature_mode if mode == "blank": return None, None, "none", None if mode == "printed_text": layer_rgba = render_printed_name_stamp(expected_name, ink_color=ink_color) return None, None, "printed", layer_rgba if mode == "genuine_correct": group, source_filter, stage = expected_group, "genuine", "case:target_signature" elif mode == "genuine_variation": group, source_filter, stage = expected_group, "genuine", "case:target_signature_variant" elif mode == "forged_skilled": group, source_filter, stage = expected_group, "forged", "case:forged_signature" elif mode == "wrong_signer_genuine": wrong_group = self.identity_registry.random_wrong_signer_group( sm.python_rng("case:wrong_signer"), expected_group, ) group, source_filter, stage = wrong_group, "genuine", "case:wrong_signature" elif mode == "role_swap": if companion_box is None: raise ValueError(f"Case {case_spec.code} requires a companion box but none is available.") group = self.identity_registry.authorized_signer_group(template.template_id, companion_box.id) source_filter, stage = "genuine", "case:role_swap_signature" elif mode == "foreign_template_signer": group, _foreign_template_id, _foreign_box_id = self.identity_registry.foreign_authorized(template.template_id) source_filter, stage = "genuine", "case:foreign_signature" else: raise ValueError(f"Unknown signature_mode: {mode!r}") record = self.signature_dataset.sample_from_group(sm.numpy_rng(stage), group, source_filter) raw = load_image_any(record.path) layer_rgba = self.preprocessor.process(raw, ink_color=ink_color) return record, group, record.source_type, layer_rgba def _select_template(self, sm: SeedManager): cfg = self.config if cfg.document.template: return self.template_provider.get(cfg.document.template) return self.template_provider.random_template(sm.numpy_rng("template_selection")) def _select_page(self, template): cfg = self.config if cfg.document.page is not None: return template.annotation.page_by_number(cfg.document.page) return template.annotation.pages[0] def _select_box(self, page_annotation, sm: SeedManager): boxes = page_annotation.signature_boxes if not boxes: raise ValueError(f"Page {page_annotation.page} has no signature boxes defined.") idx = int(sm.numpy_rng("box_selection").integers(0, len(boxes))) return boxes[idx] def _select_signature(self, sm: SeedManager): cfg = self.config if cfg.signature_selection.signature_id: return self.signature_dataset.get(cfg.signature_selection.signature_id) return self.signature_dataset.sample( sm.numpy_rng("signature_selection"), source_filter=cfg.signature_selection.source_filter, ) _WORKER_CONTEXT: "GeneratorContext | None" = None _WORKER_CONFIG: "PipelineConfig | None" = None def _init_worker(config: PipelineConfig) -> None: global _WORKER_CONTEXT, _WORKER_CONFIG _WORKER_CONFIG = config _WORKER_CONTEXT = GeneratorContext(config) def compute_extra_signature_overlays( ctx: "GeneratorContext", metadata: dict, final_image: "np.ndarray", ) -> "list[dict]": """Re-runs :class:`~src.analysis.geometry_analyzer.GeometryAnalyzer` on every OTHER signed box in this sample (companion + additional_signatures) -- purely for the before/after metrics-preview overlay, never for scoring (geometry/difficulty stay keyed to the one target box the rest of the pipeline scores). Without this, a preview of a multi-box template shows one fully-explained scored signature and one unexplained, unlabeled scribble elsewhere on the page. See :func:`src.visualization.before_after_preview.save_before_after_preview`'s ``extra_boxes`` parameter. """ template = ctx.template_provider.get(metadata["template"]) boxes_by_id = {b.id: b for b in template.annotation.pages[0].signature_boxes} canvas_size = (metadata["page_size"][0], metadata["page_size"][1]) effects = (metadata.get("augmentation") or {}).get("effects") or {} geometric_applied = any((effects.get(name) or {}).get("applied") for name in _GEOMETRIC_DOCUMENT_EFFECTS) baseline = None if geometric_applied else load_image_rgb(template.image_path) entries: "list[tuple[str, str]]" = [] companion = (metadata.get("verification") or {}).get("companion") if companion and companion.get("filled") and companion.get("box_id") in boxes_by_id: entries.append((companion["box_id"], f"{boxes_by_id[companion['box_id']].role} (companion)")) for extra in metadata.get("additional_signatures") or []: if extra["box_id"] in boxes_by_id and extra["box_id"] not in {e[0] for e in entries}: entries.append((extra["box_id"], f"{extra.get('role') or extra['box_id']} (other box)")) overlays = [] for box_id, label in entries: box = boxes_by_id[box_id] result = ctx.geometry_analyzer.analyze( final_image, target_box=box.as_tuple(), canvas_size=canvas_size, baseline_image_rgb=baseline, ) overlays.append({ "label": label, "geometry": { "target_box": list(result.target_box), "actual_box": list(result.actual_box), "signature_polygon_px": result.signature_polygon_px, "display_contours": result.display_contours, }, "metrics": { "box_coverage_pct": result.box_coverage_pct, "containment_pct": result.containment_pct, "ink_fill_ratio": result.ink_fill_ratio, "polygon_overlap_proxy": result.polygon_overlap_proxy, "mean_dark_intensity": result.mean_dark_intensity, "margin_utilization": result.margin_utilization, } if result.found else None, }) return overlays def _case_folder_name(sample_id: str, case_type: "str | None") -> str: """Every sample gets its own folder (ported from projectA's per-case-folder convention -- see the module docstring's "Output layout" note) rather than scattering flat sample_NNNNNN.png/.json pairs across output_dir. The template kind (scanned/procedural) isn't knowable until after the sample is actually generated (template selection is random per sample unless `document.template` pins it), so it can't be part of a name computed up-front for the overwrite-skip check below -- it's still recorded prominently in the ground-truth JSON's `template_kind` field and in dataset_summary.csv instead. """ return f"{sample_id}_{case_type}" if case_type else sample_id def _export_reference_signature(src_path: str, dst_path: Path) -> None: """Re-encode a reference signature image as a REAL PNG, regardless of its source format. BHSig260 ships ``.tif``; CEDAR/SigNet are already ``.png``. A previous version of this just ``shutil.copy2``'d the raw bytes under a ``*_reference_signature.png`` name -- for BHSig260-sourced signatures that left actual TIFF bytes inside a file misleadingly named ``.png``, which any standards-compliant image viewer correctly refuses to open ("error occurred while loading image"). Decoding with Pillow and re-saving guarantees the extension always matches the real content. """ with Image.open(src_path) as im: im.convert("RGB").save(dst_path) def _generate_and_export(sample_index: int) -> SampleOutcome: """Module-level worker entry point: generate one sample and write it to disk.""" assert _WORKER_CONTEXT is not None and _WORKER_CONFIG is not None, "Worker not initialized" cfg = _WORKER_CONFIG ctx = _WORKER_CONTEXT prefix = cfg.generation.filename_prefix digits = cfg.generation.filename_digits sample_id = f"{prefix}_{sample_index:0{digits}d}" output_dir = Path(cfg.paths.output_dir) case_folder = _case_folder_name(sample_id, cfg.quality.case_type) case_dir = output_dir / case_folder png_path = case_dir / f"{sample_id}_document.png" json_path = case_dir / f"{sample_id}_ground_truth.json" if not cfg.generation.overwrite and png_path.exists() and json_path.exists(): return SampleOutcome(sample_id=sample_id, success=True, error="skipped_existing", case_folder=case_folder) try: if cfg.generation.target_difficulty is not None: metadata, final_image, validation_report = ctx.run_sample_targeting_difficulty( sample_index, cfg.generation.target_difficulty, cfg.generation.difficulty_tolerance, cfg.generation.difficulty_max_attempts, ) else: metadata, final_image, validation_report = ctx.run_sample(sample_index) case_dir.mkdir(parents=True, exist_ok=True) save_image_rgb(png_path, final_image) # Copy the actual reference signature image(s) used INTO the case # folder (not just a path pointing back at the raw dataset) -- # ported from projectA's case_generation.py::save_case(), so each # case folder is a fully self-contained, portable unit: open it, # see the rendered document, the exact reference signature(s) it # was compared against, and the ground truth, with no dependency on # the raw dataset being present. `None`/missing for signature_modes # with no real ink (blank box, printed-text-only). sig_source = metadata.get("signature_source") or {} if sig_source.get("path"): try: _export_reference_signature(sig_source["path"], case_dir / f"{sample_id}_reference_signature.png") except OSError: logger.warning("Sample %s: could not copy reference signature from %s", sample_id, sig_source["path"]) companion = (metadata.get("verification") or {}).get("companion") or {} if companion.get("ref_path"): try: _export_reference_signature(companion["ref_path"], case_dir / f"{sample_id}_companion_signature.png") except OSError: logger.warning("Sample %s: could not copy companion signature from %s", sample_id, companion["ref_path"]) for extra in metadata.get("additional_signatures") or []: try: _export_reference_signature(extra["ref_path"], case_dir / f"{sample_id}_{extra['box_id']}_signature.png") except OSError: logger.warning("Sample %s: could not copy additional signature from %s", sample_id, extra["ref_path"]) ctx.metadata_exporter.export(metadata, json_path) if cfg.generation.save_visualization: viz_path = case_dir / f"{sample_id}_visualization.png" save_visualization(viz_path, final_image, metadata) if cfg.generation.save_before_after_preview and ctx.last_clean_image is not None: # Grouped in one shared folder rather than scattered one-per-case -- # easier to flip through every sample's metrics preview in a row # without opening each case folder individually. before_after_path = output_dir / "before_after" / f"{sample_id}_before_after.png" extra_boxes = compute_extra_signature_overlays(ctx, metadata, final_image) save_before_after_preview(before_after_path, ctx.last_clean_image, final_image, metadata, cfg.difficulty, extra_boxes) verification = metadata.get("verification") or {} outcome = SampleOutcome( sample_id=sample_id, success=True, difficulty_tier=metadata["difficulty"]["tier"], difficulty_score=metadata["difficulty"]["score"], case_folder=case_folder, template_id=metadata["template"], template_kind=metadata["template_kind"], case_type=verification.get("case_type"), verdict=verification.get("verdict"), reject_code=verification.get("reject_code"), signer_name=metadata["signer"]["name"], ) if validation_report is not None: outcome.validation_passed = validation_report.passed outcome.validation_errors = len(validation_report.errors) outcome.validation_warnings = len(validation_report.warnings) if not validation_report.passed: logger.warning( "Sample %s failed validation: %s", sample_id, "; ".join(i.message for i in validation_report.errors), ) return outcome except Exception as exc: # noqa: BLE001 - report and continue the batch logger.exception("Failed to generate sample %s", sample_id) return SampleOutcome(sample_id=sample_id, success=False, error=str(exc), case_folder=case_folder) @dataclass class GenerationSummary: """Batch-level summary returned by :meth:`DatasetGenerator.generate`.""" total: int succeeded: int failed: int skipped_existing: int validation_passed: int validation_failed: int tier_counts: dict[str, int] failed_samples: list[str] def as_dict(self) -> dict[str, Any]: return { "total": self.total, "succeeded": self.succeeded, "failed": self.failed, "skipped_existing": self.skipped_existing, "validation_passed": self.validation_passed, "validation_failed": self.validation_failed, "tier_counts": self.tier_counts, "failed_samples": self.failed_samples, } class DatasetGenerator: """Drives batch generation of a synthetic signed-document dataset. Example: >>> generator = DatasetGenerator(config) >>> summary = generator.generate() """ def __init__(self, config: PipelineConfig) -> None: self.config = config Path(config.paths.output_dir).mkdir(parents=True, exist_ok=True) def generate(self) -> GenerationSummary: """Generate ``config.generation.count`` samples, sequentially or via a worker pool.""" cfg = self.config indices = list(range(cfg.generation.start_index, cfg.generation.start_index + cfg.generation.count)) outcomes: list[SampleOutcome] = [] if cfg.generation.workers <= 1: _init_worker(cfg) for idx in tqdm(indices, desc="Generating samples", unit="doc"): outcomes.append(_generate_and_export(idx)) else: with ProcessPoolExecutor( max_workers=cfg.generation.workers, initializer=_init_worker, initargs=(cfg,), ) as pool: futures = {pool.submit(_generate_and_export, idx): idx for idx in indices} for future in tqdm(as_completed(futures), total=len(futures), desc="Generating samples", unit="doc"): outcomes.append(future.result()) self._write_summary_csv(outcomes) return self._summarize(outcomes) def _write_summary_csv(self, outcomes: "list[SampleOutcome]") -> None: """One row per sample -- a human-scannable overview of the whole batch (case folder, which template/kind it landed on, verdict, difficulty) without opening every ground_truth.json individually. Written regardless of workers=1 vs multi-process, since it's built from the already-collected SampleOutcome list, not during generation itself. """ path = Path(self.config.paths.output_dir) / "dataset_summary.csv" fieldnames = [ "sample_id", "case_folder", "success", "template_id", "template_kind", "case_type", "verdict", "reject_code", "signer_name", "difficulty_tier", "difficulty_score", ] with path.open("w", newline="", encoding="utf-8") as f: writer = csv.DictWriter(f, fieldnames=fieldnames) writer.writeheader() for o in outcomes: writer.writerow({ "sample_id": o.sample_id, "case_folder": o.case_folder, "success": o.success, "template_id": o.template_id, "template_kind": o.template_kind, "case_type": o.case_type, "verdict": o.verdict, "reject_code": o.reject_code, "signer_name": o.signer_name, "difficulty_tier": o.difficulty_tier, "difficulty_score": o.difficulty_score, }) logger.info("Wrote dataset summary to %s", path) @staticmethod def _summarize(outcomes: list[SampleOutcome]) -> GenerationSummary: succeeded = [o for o in outcomes if o.success] failed = [o for o in outcomes if not o.success] skipped = [o for o in succeeded if o.error == "skipped_existing"] validated = [o for o in succeeded if o.validation_passed is not None] validation_passed = sum(1 for o in validated if o.validation_passed) validation_failed = sum(1 for o in validated if not o.validation_passed) tier_counts: dict[str, int] = {} for o in succeeded: if o.difficulty_tier: tier_counts[o.difficulty_tier] = tier_counts.get(o.difficulty_tier, 0) + 1 summary = GenerationSummary( total=len(outcomes), succeeded=len(succeeded), failed=len(failed), skipped_existing=len(skipped), validation_passed=validation_passed, validation_failed=validation_failed, tier_counts=tier_counts, failed_samples=[o.sample_id for o in failed], ) logger.info("Generation summary: %s", summary.as_dict()) return summary
"""Top-level orchestration: DatasetGenerator drives the full per-sample pipeline.
For every sample this wires together, in order:
1. :class:`~src.templates.template_loader.TemplateLoader` -- pick a template + signature box.
2. :class:`~src.signatures.signature_dataset.SignatureDataset` -- pick a signature image.
3. :class:`~src.rendering.signature_preprocessor.SignaturePreprocessor` -- clean it into an RGBA stamp.
4. :class:`~src.placement.placement_engine.PlacementEngine` -- fit/rotate/position it.
5. :class:`~src.augmentation.augmentation_engine.AugmentationEngine` -- signature-layer effects.
6. :class:`~src.rendering.renderer.Renderer` -- blend onto the document.
7. :class:`~src.augmentation.augmentation_engine.AugmentationEngine` -- document-level effects.
8. :class:`~src.analysis.geometry_analyzer.GeometryAnalyzer` -- detect + measure.
9. :class:`~src.analysis.difficulty_analyzer.DifficultyAnalyzer` -- score.
10. :class:`~src.metadata.metadata_exporter.MetadataExporter` -- assemble + write JSON.
11. :class:`~src.analysis.validation_engine.ValidationEngine` -- verify.
A single :class:`GeneratorContext` holds all stateless-between-calls engine
instances for one process; :class:`DatasetGenerator` either drives it
directly (``workers=1``) or fans it out across a
:class:`concurrent.futures.ProcessPoolExecutor` pool, where each worker
process builds exactly one context via ``_init_worker`` and reuses it for
every sample it is assigned. Because every random draw is derived purely
from ``(master_seed, sample_index, stage)``, results are identical
regardless of worker count or scheduling order.
"""
from __future__ import annotations
import csv
import shutil
from concurrent.futures import ProcessPoolExecutor, as_completed
from dataclasses import dataclass
from pathlib import Path
from typing import Any
import numpy as np
from PIL import Image
from tqdm import tqdm
from src.analysis.difficulty_analyzer import DifficultyAnalyzer
from src.analysis.geometry_analyzer import GeometryAnalyzer
from src.analysis.validation_engine import ValidationEngine, ValidationReport, summarize
from src.augmentation.augmentation_engine import AugmentationEngine
from src.config.schema import DifficultyWeights, PipelineConfig, PlacementConfig, Range
from src.cosmetics.cosmetic_fields import fill_all_cosmetic_fields
from src.cosmetics.scanned_cosmetic_fields import fill_scanned_cosmetic_fields
from src.metadata.metadata_exporter import MetadataExporter
from src.placement.placement_engine import PlacementEngine, PlacementResult
from src.rendering.printed_text import render_printed_name_stamp
from src.rendering.renderer import Renderer
from src.rendering.signature_preprocessor import SignaturePreprocessor
from src.signatures.signature_dataset import SignatureDataset, SignatureRecord
from src.templates.annotation_schema import SignatureBoxAnnotation, TemplatePageAnnotation
from src.templates.procedural_template_provider import ProceduralTemplateProvider
from src.templates.template_loader import Template, TemplateLoader
from src.templates.template_provider import CompositeTemplateProvider, TemplateProvider, template_kind
from src.utils.image_io import load_image_any, load_image_rgb, save_image_rgb
from src.utils.logging_utils import get_logger
from src.utils.names import generate_name, generate_role
from src.utils.random_utils import SeedManager, resolve_scalar_or_range
from src.verification.case_types import CASE_TABLE, CaseSpec
from src.verification.registry import SignerIdentityRegistry
from src.visualization.before_after_preview import save_before_after_preview
from src.visualization.visualizer import save_visualization
logger = get_logger(__name__)
INK_COLOR_POOL: tuple[tuple[int, int, int], ...] = (
(15, 15, 20), # black
(18, 22, 58), # blue-black
(24, 34, 96), # ballpoint blue
(12, 12, 14), # deep black
)
# DifficultyWeights' schema defaults for these fields are the deck's
# literal, generic reference constants (0.04 / 90 / 210 / 60) -- measured
# (see configs/procedural_templates.yaml's own history) to peg smallness/
# faintness near their ceiling for almost any real signature on this
# pipeline's own templates, especially procedural ones (real signature area
# is ~0.2-1.5% of the page vs. the deck's assumed 4% "normal"). Previously
# this recalibration only applied if the whole run used
# `--config configs/procedural_templates.yaml`, which meant a
# `template_provider: both` batch (or the plain CLI default) silently used
# the deck-literal, too-aggressive constants for procedural samples anyway.
# Applied automatically per-sample below, keyed on template_kind(), instead.
#
# faintness_dark_ref and low_texture_reference_stddev refit 2026-08-11
# against a fresh 60-sample natural draw of real procedural output
# (mean_dark_intensity: p10=164.0/median=180.6/p90=195.7; gray_stddev:
# p10=25.3/median=34.6/p90=46.5) -- the prior faintness_dark_ref (184) sat
# ABOVE the real median (180.6), so `clamp01((dark_intensity-dark_ref)/...)`
# floored to exactly 0.000 for every sample in a fresh measurement (20% of
# the total score, contributing nothing, discriminating nothing, for the
# entire procedural template family). Re-anchored to real p10 (~164, rounded
# to 165) so faintness has genuine spread across the real distribution
# instead of a constant zero: median sample now scores ~0.30, darkest
# decile ~0, lightest observed (~208) ~0.79. low_texture_reference_stddev
# was never split from the deck-literal default at all (only smallness/
# faintness were, historically) despite the same underlying asymmetry
# existing here too -- anchored to real p90 (~46.5, rounded to 46) so the