Add unified_pipeline: merged signature-verification synthetic document generator (part 15)
65cc549 verified Download unified_pipeline/src/generator.py from InternsProgressUpdate/Asyira: direct link, hf CLI and curl.
- Browser
- Download file 64.4 kB
-
https://huggingface.co/InternsProgressUpdate/Asyira/resolve/main/unified_pipeline/src/generator.py
- Command line
-
hf download hf://InternsProgressUpdate/Asyira/unified_pipeline/src/generator.py
-
curl -L -o generator.py https://huggingface.co/InternsProgressUpdate/Asyira/resolve/main/unified_pipeline/src/generator.py
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