Add files using upload-large-folder tool

.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+.venv/
+venv/
+.pytest_cache/
+*.egg-info/
+
+output/*.png
+output/*.json
+output/visualizations/
+output/.cache/
+!output/.gitkeep

README.md

@@ -0,0 +1,546 @@
+# Synthetic Signed Bank Document Generator
+
+A modular, deterministic, configuration-driven pipeline that takes scanned
+bank document templates with blank signature fields, fills them with
+realistic handwritten signatures drawn from a public signature dataset,
+applies configurable physical/scanner degradation, and exports both the
+rendered document and a comprehensive per-sample metadata JSON — suitable
+for training and benchmarking document-AI / signature-verification models.
+
+```
+python main.py --config configs/generate.yaml --count 10000
+```
+
+---
+
+## Table of contents
+
+1. [Installation](#installation)
+2. [Project layout](#project-layout)
+3. [Input assets](#input-assets)
+4. [Quick start](#quick-start)
+5. [Configuration](#configuration)
+6. [Architecture / pipeline stages](#architecture--pipeline-stages)
+7. [Metadata schema](#metadata-schema)
+8. [Verification test cases](#verification-test-cases)
+9. [Difficulty scoring](#difficulty-scoring)
+10. [Signature box annotation](#signature-box-annotation)
+11. [Determinism & reproducibility](#determinism--reproducibility)
+12. [Validation](#validation)
+13. [Visualization](#visualization)
+14. [Testing](#testing)
+15. [Extending the pipeline](#extending-the-pipeline)
+
+---
+
+## Installation
+
+Requires **Python 3.12+** (developed and tested against 3.11.9 as well; no
+3.12-only syntax is used, so 3.11 works too).
+
+```bash
+python -m venv .venv
+source .venv/bin/activate        # Windows: .venv\Scripts\activate
+pip install -r requirements.txt
+```
+
+Core dependencies: OpenCV, NumPy, SciPy, Pillow, scikit-image, Shapely,
+PyYAML, Pydantic, Albumentations, OmegaConf, Matplotlib, tqdm, pytest.
+
+## Project layout
+
+```
+cc/
+├── image/                    # 9 scanned bank document templates (provided)
+├── dataset/                  # Public handwritten signature dataset (provided)
+├── annotations/              # Signature box annotations, one JSON per template
+├── configs/
+│   ├── default.yaml          # Every config field with its default value
+│   ├── generate.yaml         # Example large-batch dataset config
+│   └── examples/             # Focused example configs (see below)
+├── output/                   # Generated PNG + JSON land here
+├── src/
+│   ├── config/                # Pydantic schema + OmegaConf loader
+│   ├── templates/             # TemplateLoader, annotation schema, CV box detector
+│   ├── signatures/             # SignatureDataset discovery/sampling
+│   ├── rendering/              # SignaturePreprocessor, Renderer (blending)
+│   ├── placement/              # PlacementEngine
+│   ├── augmentation/           # AugmentationEngine + effect implementations
+│   ├── analysis/                # GeometryAnalyzer, DifficultyAnalyzer, ValidationEngine
+│   ├── verification/             # Verification test-case registry + CASE_TABLE (case_type 1a-5b)
+│   ├── metadata/                # MetadataExporter
+│   ├── visualization/           # Debug figure rendering
+│   ├── utils/                   # Logging, seeding, geometry, I/O, names
+│   └── generator.py             # DatasetGenerator orchestrator (+ multiprocessing)
+├── tests/                     # pytest unit + integration tests
+├── main.py                    # CLI entry point
+└── requirements.txt
+```
+
+## Input assets
+
+This repository ships with:
+
+* **`image/`** — 9 real scanned bank document templates (guarantee letters,
+  loan agreements, account mandates), auto-discovered recursively regardless
+  of subfolder layout. Each gets a stable id `bank_doc_01` … `bank_doc_09`,
+  assigned by a deterministic sort of their discovered paths.
+* **`dataset/`** — A public handwritten signature dataset (CEDAR-style:
+  `genuine/original_<signer>_<sample>.png` and
+  `forged/forgeries_<signer>_<sample>.png`), auto-discovered recursively.
+  Nested `dataset/personNNN/*.png`-style layouts are also supported — the
+  loader falls back to using each signature's parent folder name as its
+  signer group when the CEDAR filename pattern doesn't match, and to an
+  auto-generated id when no identity can be inferred at all. An optional
+  `dataset/metadata.csv` with `path`/`filename` + `signer`/`source_type`
+  columns can override both the identity association and genuine/forged
+  labeling for any file, plus an optional `script` column (`"latin"` by
+  default) recording the handwriting script a signature is written in.
+  `dataset/hindi_bengali/` + the matching rows in `dataset/metadata.csv`
+  bundle 7 real, named, multi-script signers (Hindi/Devanagari-style,
+  Bengali-style, and Latin cursive) alongside the 55 anonymous CEDAR
+  identities, so generated samples aren't exclusively Latin-script English
+  names — `SignerIdentityRegistry.display_name()` (`src/verification/registry.py`)
+  returns a metadata.csv-sourced name as-is instead of generating one, and
+  every `SignatureRecord`/`verification` metadata block carries its `script`.
+  These signers have very few reference samples each (1-3, no forged
+  counterpart) — `records_for_group(..., "forged")` falls back to their
+  genuine samples with a logged warning rather than failing, so the `3b`
+  skilled-forgery case degrades gracefully rather than erroring for them.
+
+Nothing about either directory's internal layout is hardcoded — add more
+template images or more signature images/folders and they will be picked up
+automatically on the next run.
+
+## Quick start
+
+```bash
+# 1. Generate 10 samples with all defaults (configs/default.yaml)
+python main.py
+
+# 2. Generate a large, varied batch
+python main.py --config configs/generate.yaml --count 10000
+
+# 3. Generate one fully reproducible, fixed-identity sample with a debug figure
+python main.py --config configs/examples/single_document_demo.yaml --save-visualization
+
+# 4. Override arbitrary nested config values from the command line
+python main.py --set placement.rotation_deg.max=6 --set augmentation.coffee_stain.enabled=true
+
+# 5. Restrict to one template, use 8 worker processes, don't overwrite existing files
+python main.py --template bank_doc_03 --count 5000 --workers 8
+```
+
+Every run writes `output/<prefix>_<NNNNNN>.png` + `.json` pairs, plus
+`output/generation_summary.json` (batch statistics) and
+`output/resolved_config.yaml` (the fully-resolved config actually used, for
+provenance/reproduction).
+
+### CLI reference
+
+| Flag | Effect |
+|---|---|
+| `--config PATH` | User YAML merged on top of `configs/default.yaml` |
+| `--count N` | Number of samples |
+| `--seed N` | Master random seed |
+| `--workers N` | Worker process count (`1` = sequential, in-process) |
+| `--output DIR` | Output directory |
+| `--template ID` | Force every sample to use one template (e.g. `bank_doc_03`) |
+| `--start-index N` | First sample number (for resuming/sharding a batch) |
+| `--overwrite` | Regenerate samples even if their files already exist |
+| `--save-visualization` | Also write a debug figure per sample |
+| `--set key.path=value` | Arbitrary dot-path config override (repeatable) |
+| `--log-level LEVEL` | `DEBUG` / `INFO` / `WARNING` / `ERROR` |
+
+## Configuration
+
+Configuration is layered: `configs/default.yaml` (every field, documented) →
+an optional `--config` user YAML (merged on top) → `--set key=value` CLI
+overrides (highest precedence). The merged result is validated against a
+Pydantic schema (`src/config/schema.py`) — invalid types, out-of-range
+values, or unknown keys fail fast with a clear error instead of silently
+being ignored.
+
+Any placement/augmentation numeric parameter accepts either a fixed scalar
+or a range, resolved independently per sample by a seeded RNG:
+
+```yaml
+placement:
+  scale_factor: 0.84          # fixed
+  rotation_deg:
+    min: -5
+    max: 5                    # sampled uniformly per sample
+```
+
+Every augmentation effect follows the same shape:
+
+```yaml
+augmentation:
+  coffee_stain:
+    enabled: true
+    strength: 0.42             # or {min: ..., max: ...}
+    probability: 0.1            # per-sample chance of actually applying
+    seed: null                  # optional explicit seed; default derives from (master_seed, sample_index, name)
+```
+
+These effects are covered by **20 configurable families** (a couple are
+strict specializations of another and share one family with a `type`/`tone`
+selector, so the config surface stays coherent):
+
+| Family | Covers |
+|---|---|
+| `rotation` | Extra probabilistic jitter on top of `placement.rotation_deg` |
+| `stroke_dilation` | Ink stroke thickness variation |
+| `motion_blur`, `gaussian_blur` | Signature-layer blur |
+| `perspective` | Whole-page perspective warp |
+| `scanner_noise`, `salt_pepper` | Sensor/impulse noise |
+| `jpeg_compression` | Lossy re-encode artifacts (applied last) |
+| `contrast`, `gamma` | Photometric shifts |
+| `coffee_stain` | Coffee-ring blotches |
+| `stain` (`type: paper\|water\|random`) | Paper stains + water stains |
+| `shadow` (`type: edge\|corner\|fold\|random`) | Edge / corner / fold shadows |
+| `crumple` | Paper crumpling + wrinkle lines |
+| `discoloration` (`tone: yellow\|grey\|sepia\|random`) | General discoloration + paper yellowing |
+| `page_tilt` | Crooked scanner feed |
+| `dust`, `scanner_streaks` | Sensor debris / dirty-glass streaks |
+| `ink_fading`, `ink_bleed` | Ink density effects |
+
+See `configs/default.yaml` for every field and its default, and
+`configs/generate.yaml` / `configs/examples/*.yaml` for worked examples
+(a large varied batch, a fixed-identity single-document demo, an "easy"
+preset, and a "hard/degraded" preset).
+
+## Architecture / pipeline stages
+
+Each sample flows through the same 11 stages the spec describes, one class
+per stage:
+
+| # | Stage | Class |
+|---|---|---|
+| 1 | Load template | `TemplateLoader` |
+| 2 | Resolve signature box(es) | `TemplateLoader` (manual annotation, or CV auto-detect fallback) |
+| 3 | Assign signer name/role | `src.utils.names` + config |
+| 4 | Select a signature image | `SignatureDataset` |
+| 5 | Clean/preprocess signature | `SignaturePreprocessor` |
+| 6 | Fit & position in box | `PlacementEngine` |
+| 7 | Signature-layer augmentation | `AugmentationEngine.apply_to_signature` |
+| 8 | Blend onto document | `Renderer` |
+| 9 | Document-level augmentation | `AugmentationEngine.apply_to_document` |
+| 10 | Detect rendered signature + geometry | `GeometryAnalyzer` |
+| 11 | Difficulty score | `DifficultyAnalyzer` |
+| — | Export | `MetadataExporter` |
+| — | Verify | `ValidationEngine` |
+
+`GeneratorContext` (in `src/generator.py`) wires all of the above together
+for one sample; `DatasetGenerator` drives it across a batch, either
+sequentially (`workers=1`) or via a `ProcessPoolExecutor` where each worker
+builds one `GeneratorContext` (via a pool initializer) and reuses it for
+every sample it's assigned.
+
+### Signature cleaning (`SignaturePreprocessor`)
+
+Signature dataset images are flat grayscale/RGB scans with no alpha
+channel. The preprocessor estimates the local paper background level,
+derives a soft per-pixel alpha from how dark each pixel is relative to that
+background (gamma-softened to preserve antialiased stroke edges/natural
+texture rather than a hard binary mask), removes sub-pixel speckle noise via
+connected-component filtering, and tightly crops to the ink content. A
+flat ink color (randomly chosen per sample from a small realistic pool —
+black, blue-black, ballpoint blue) is applied to the RGB channels; the alpha
+channel carries all of the texture.
+
+### Placement (`PlacementEngine`)
+
+Rotates first (about the signature's own center, on an auto-expanding
+transparent canvas so nothing clips), then scales to fit the box's
+margin-adjusted interior while preserving aspect ratio (never stretches),
+then positions via an anchor point (`center`, `top_left`, …) plus
+pixel offsets. A configurable `misplacement_probability` optionally kicks
+the signature away from its anchored position by up to
+`misplacement_strength * max(box_w, box_h)` in a random direction — the
+mechanism behind intentionally "hard" (badly-placed) samples.
+A signature is never allowed to shrink below a legible minimum height
+(16px) even inside a very short box; on the real bundled templates several
+signature lines are only 12-24px tall, and a naive fit-to-box scale would
+otherwise render an invisible, sub-pixel signature.
+
+### Rendering (`Renderer`)
+
+Supports `multiply`, `darken`, and `alpha` blend modes, configurable ink
+opacity, alpha-edge feathering (`feather_px`), an overall blur to match scan
+resolution (`blur_sigma`), a light Gaussian sensor-noise pass baked into
+every render, and a final mild anti-aliasing blur.
+
+### Detection (`GeometryAnalyzer`)
+
+Detection is scoped to the *known* signature field (the annotated box, and,
+if nothing is found there, a widened window around the union of the box and
+the pre-augmentation placement location) rather than searching the whole
+page — exactly how a real pipeline would use its layout annotations, and
+what makes the box-vs-detection coverage metrics meaningful in the first
+place. Ink is separated from the local paper background via adaptive
+thresholding; a heuristic filter discards thin, wide, solid components
+(printed "sign here" rule lines) so a blank field is never mistaken for a
+signature. From the resulting ink mask it computes: axis-aligned bounding
+box, `cv2.minAreaRect` minimum rotated rectangle, a convex-hull polygon,
+centroid, PCA-based orientation, ink pixel count, `box_coverage_pct`,
+`containment_pct`, `ink_fill_ratio`, `polygon_overlap_proxy` (IoU),
+distance from box center, and margin utilization.
+
+## Metadata schema
+
+One JSON per sample, always containing the full schema (fields for
+augmentations that weren't applied are present with a neutral value, not
+omitted):
+
+```jsonc
+{
+  "document_id": "sample_000001",
+  "template": "bank_doc_03",
+  "document_type": "deed_of_guarantee",
+  "page": 1, "page_size": [1024, 559], "dpi": 300,
+  "signer": {"name": "Jane Doe", "role": "Guarantor (Authorized Signatory)"},
+  "signature_source": {"signature_id": "sig_001437", "path": "dataset/genuine/original_14_7.png",
+                         "signer_group": "signer_0014", "source_type": "genuine"},
+  "placement": {"x_offset": 8.0, "y_offset": -4.0, "rotation_deg": -3.0, "scale_factor": 0.84,
+                 "anchor_point": "center", "misplaced": false, ...},
+  "rendering": {"blend_mode": "multiply", "ink_opacity": 0.91, "blur_sigma": 0.34, ...},
+  "difficulty": {"score": 0.57, "tier": "medium", "misplacement": 0.38, "whitespace": 0.14,
+                  "faintness": 0.45, "smallness": 0.31, "low_texture": 0.12},
+  "quality": {"degraded": false, "scanner_quality": 0.85, "paper_quality": 0.85, "render_quality": 0.85},
+  "verification": {
+    "case_type": "3a", "verdict": "REJECT", "reject_code": "IDENTITY_MISMATCH",
+    "target_box_id": "sig1", "expected_signer_group": "signer_0014", "expected_signer_script": "latin",
+    "actual_signer_group": "signer_0027", "actual_source_type": "genuine", "actual_signer_script": "latin",
+    "companion": null
+  },
+  "augmentation": {
+    "rotate_deg": -2, "scale_factor": 0.84, "stroke": 0.12, "noise_amount": 0.06,
+    "stain_type": null, "stain_strength": 0.0, "shadow_type": "corner", "shadow_strength": 0.55,
+    "coffee_stain_strength": 0.42, "crumple_strength": 0.18, "tilt_deg": 1.3,
+    "discoloration_strength": 0.0, "blur_sigma": 0.35, "jpeg_quality": 82, "scanner_noise": 0.02,
+    "effects": { "...every single effect, always present, with enabled/applied/strength/probability/seed/params...": {} }
+  },
+  "geometry": {
+    "box_px": [1200, 830, 1530, 950], "target_box": [...], "actual_box": [...],
+    "signature_bbox_px": [...], "signature_polygon_px": [[x, y], ...], "convex_hull_px": [...],
+    "min_rotated_rect": {"center": [...], "size": [...], "angle_deg": ...},
+    "centroid_px": [...], "orientation_deg": ..., "ink_pixels": ..., "detected": true
+  },
+  "metrics": {
+    "box_coverage_pct": 84.2, "containment_pct": 96.3, "ink_fill_ratio": 0.28,
+    "polygon_overlap_proxy": 0.71, "distance_from_box_center_px": 12.4, "margin_utilization": 0.6,
+    "mean_dark_intensity": 142.1, "gray_stddev": 38.6, "signature_area_ratio": 0.011
+  },
+  "provenance": {"master_seed": 1234, "sample_index": 1}
+}
+```
+
+The `augmentation.effects.<name>` block is the full audit trail for every
+one of the 20 effect families: whether it was `enabled` in config, whether
+its probability roll actually `applied` it, the resolved `strength`, and
+any effect-specific `params` (e.g. `{"resolved_type": "corner"}` for
+shadow, `{"quality": 58}` for JPEG compression) — this is present even when
+`applied: false`, so the schema is identical across every sample regardless
+of what happened to fire.
+
+`quality.degraded` is `true` iff `quality.case_type == "1d"` **or**
+`quality.notes` contains the substring `"low-quality"` (case-insensitive) —
+both driven by `quality.case_type` / `quality.notes` in config (see
+`configs/examples/hard_degraded.yaml`). `verification` is present (with
+every field `null`) on every sample; see the next section for when it's
+populated.
+
+## Verification test cases
+
+Setting `quality.case_type` to one of 12 recognized codes switches sample
+generation into **scenario-driven mode**: instead of a random genuine
+signature in a random box, the pipeline renders the specific scenario the
+code describes and stamps the sample's `verification` metadata block with
+the matching ground-truth `verdict`/`reject_code` — producing a labeled
+benchmark for a downstream verifier. Any other value (or leaving it unset)
+behaves exactly as before.
+
+| Code | Scenario | Verdict | Reject code |
+|---|---|---|---|
+| `1a` | Correct signer signs normally | PASS | - |
+| `1b` | Correct signer, natural pen variation (a different genuine sample of the same person) | PASS | - |
+| `1c` | Multi-signer form, both boxes sign correctly | PASS | - |
+| `1d` | Correct signer, scan degraded (pair with `configs/examples/hard_degraded.yaml`) | PASS | - |
+| `2a` | Box left completely blank | REJECT | `NO_SIGNATURE` |
+| `2b` | Printed/typed name only, no handwriting | REJECT | `NO_SIGNATURE` |
+| `3a` | Wrong real person signs the box (a different genuine signer) | REJECT | `IDENTITY_MISMATCH` |
+| `3b` | Skilled-forgery sample used (CEDAR `forged/` sample of the authorized signer) | REJECT | `IDENTITY_MISMATCH` |
+| `4a` | Authorized signer, but wrong role's box (the *other* box's authorized signer signs here instead) | REJECT | `ROLE_MISMATCH` |
+| `4b` | Signer from a different form entirely (authorized elsewhere, not on this template) | REJECT | `ROLE_MISMATCH` |
+| `5a` | Required signer's box left empty (while a companion box is correctly signed) | REJECT | `REQUIRED_SIGNER_ABSENT` |
+| `5b` | Someone else signs in the required signer's place (while a companion box is correctly signed) | REJECT | `REQUIRED_SIGNER_ABSENT` |
+
+```bash
+python main.py --config configs/examples/verification_cases.yaml --set quality.case_type=3a --count 10
+python scripts/generate_verification_suite.py --per-case 2   # one labeled batch covering all 12 codes
+```
+
+### How ground truth is derived
+
+`src/verification/registry.py`'s `SignerIdentityRegistry` deterministically
+assigns an "authorized signer" identity (one of the discovered CEDAR signer
+groups) to every `(template_id, box_id)` pair, purely as a function of the
+master seed — there's no persisted state, consistent with the rest of the
+pipeline's seeding model. Every case type is defined declaratively in
+`src/verification/case_types.py` (`CASE_TABLE`) as what should actually be
+rendered (`signature_mode`: genuine-correct, blank, printed-text,
+wrong-signer, skilled-forgery, role-swap, foreign-template-signer, ...) plus
+whether a companion box on the same page should also be filled with its own
+correctly-authorized signature (`1c`/`5a`/`5b` — the cases whose label only
+makes sense in a multi-signer-page context). The `verification` metadata
+block records both the expected and actual signer group so the label is
+independently auditable, not just asserted.
+
+Companion-box rendering exists purely for visual/contextual realism (so a
+"required signer absent" sample actually shows a properly multi-signed
+page); it does not get its own `geometry`/`difficulty` block — the schema
+stays single-target-box-centric, same as it's always been. `signature_source`
+is `null` for the two blank scenarios (`2a`/`5a`); the expected identity in
+that case lives only in `verification.expected_signer_group`.
+
+## Difficulty scoring
+
+Computed exactly as specified, from the post-render, post-augmentation
+detected geometry (a pure function — no randomness — so it is always
+reproducible from its own recorded components):
+
+```
+misplacement = clamp(1 - polygon_overlap_proxy, 0, 1)
+whitespace   = clamp(whitespace_ratio, 0, 1)              # whitespace_ratio = 1 - ink_fill_ratio
+faintness    = clamp((mean_dark_intensity - 90) / 120, 0, 1)
+smallness    = clamp(1 - signature_area_ratio / 0.04, 0, 1)
+low_texture  = clamp(1 - gray_stddev / 60, 0, 1)
+
+score = 0.35*misplacement + 0.20*whitespace + 0.20*faintness + 0.15*smallness + 0.10*low_texture
+
+tier = "easy" if score < 0.33 else "medium" if score < 0.66 else "hard"
+```
+
+**A note on the bundled templates:** `smallness` uses a fixed reference of
+4% of page area. On the 9 real bank forms shipped in `image/`, the actual
+signature lines are (realistically) much smaller than that — typically
+0.2%–1.5% of the page — so `smallness`, and with it the overall score, runs
+structurally high (mostly `medium`/`hard`) even under the "clean" example
+preset. This is an accurate reflection of how small real bank-form
+signature fields are relative to a full page, not a bug in the scoring
+formula, which is intentionally implemented exactly as specified (weights
+and the `0.04` reference are not something the pipeline silently retunes).
+If your use case wants a different-looking tier distribution, adjust
+`difficulty.easy_threshold` / `difficulty.hard_threshold` in config, or
+supply larger signature boxes in your own annotations.
+
+## Signature box annotation
+
+Two modes, in order of preference:
+
+* **Mode 2 — manual annotation (preferred, used for all 9 bundled
+  templates):** `annotations/<template_id>.json`:
+
+  ```json
+  {
+    "id": "bank_doc_03",
+    "source_image": "image/guarantee/image.png",
+    "document_type": "deed_of_guarantee",
+    "pages": [{
+      "page": 1, "page_size": [1024, 559], "dpi": 300,
+      "signature_boxes": [
+        {"id": "sig1", "x1": 595, "y1": 399, "x2": 748, "y2": 431,
+         "role": "Guarantor (Authorized Signatory)", "name": "Guarantor"}
+      ]
+    }]
+  }
+  ```
+
+  The 9 bundled annotation files were hand-measured against each template
+  image (using a coordinate-grid overlay for precision) — every signature
+  field, its role, and page geometry are captured exactly.
+
+* **Mode 1 — automatic CV detection (fallback):** if no
+  `annotations/<template_id>.json` exists for a discovered template,
+  `src/templates/box_detector.py` looks for long horizontal "sign here"
+  rule lines (morphological opening + contour filtering) and places a
+  candidate box directly above each one. The result is cached back to
+  `annotations/<template_id>.json` so detection only ever runs once per
+  template — subsequent runs (including a fresh checkout with new
+  templates dropped into `image/`) reuse the cached annotation. If a
+  template has no such lines at all, a generic lower-right fallback box is
+  used so the pipeline never crashes on an unannotated template.
+
+To add a 10th template: drop its image into any subfolder of `image/` and
+either let auto-detection run once, or hand-author its annotation file
+(fastest way: temporarily overlay a coordinate grid on the image — see the
+`_grid_debug` pattern used during development — and read off box corners).
+
+## Determinism & reproducibility
+
+Every random draw anywhere in the pipeline comes from an RNG whose seed is
+`sha256(master_seed | sample_index | stage_name)` (`src/utils/random_utils.py`),
+never from a shared/global RNG. Consequences:
+
+* The same `(seed, config)` always produces byte-identical PNGs and
+  semantically identical JSON, regardless of `--workers` or scheduling order
+  (verified in `tests/test_end_to_end.py`, and by hand: a `workers=1` run
+  and a `workers=4` run of the same seed produce `cmp`-identical PNGs).
+* Every individual augmentation effect's own `seed` field in its metadata
+  record is independently derivable/overridable — set `augmentation.<name>.seed`
+  explicitly in config to pin one specific effect while leaving everything
+  else seed-derived.
+* `output/resolved_config.yaml` captures the exact fully-resolved
+  configuration used for a run, so it can be handed to `--config` later to
+  reproduce that run exactly (given the same `--seed`).
+
+## Validation
+
+`ValidationEngine` runs (by default) after every sample and checks:
+metadata schema completeness, the signature was actually detected, its
+polygon is non-degenerate and geometrically valid, every bounding box is
+well-formed, boxes lie on the page (a warning, or an error under
+`validation.strict: true`), no `NaN`/`Inf` leaked into the JSON, and the
+difficulty score/tier are exactly reproducible from their own recorded
+components. Per-sample pass/fail rolls up into
+`output/generation_summary.json`. Disable with `generation.run_validation: false`.
+
+## Visualization
+
+`--save-visualization` writes `output/visualizations/<id>_viz.png` per
+sample: the full rendered document with the target box (green), detected
+bounding box (blue), and detected polygon (red) overlaid; a crop of the
+signature field; the reconstructed detected-ink mask; a coverage-metrics
+readout; and a difficulty-component bar chart.
+
+## Testing
+
+```bash
+python -m pytest -q
+```
+
+80 tests covering geometry math (coverage/containment/IoU/margin
+utilization), the exact difficulty formula (including weight-sum
+validation and clamping), seed derivation/independence, placement
+(determinism, aspect-ratio preservation, the minimum-height floor,
+misplacement gating), signature/template discovery against the real
+bundled assets (including the multi-script named signer pool), ink
+detection (including the printed-rule-line false-positive guard), metadata
+validation, full end-to-end reproducibility, and the case_type-driven
+verification scenarios (`tests/test_verification_cases.py`: registry
+determinism, ground truth for all 12 codes, multi-script signer handling,
+and backward compatibility with the non-case-type path).
+
+## Extending the pipeline
+
+* **New augmentation effect:** add a function to
+  `src/augmentation/document_effects.py` or `signature_effects.py`, a field
+  to `AugmentationsConfig` in `src/config/schema.py`, and a branch in
+  `AugmentationEngine.apply_to_document`/`apply_to_signature`.
+* **New template:** drop an image into `image/`; annotate manually or let
+  auto-detection + caching handle it.
+* **New signature source:** drop images anywhere under `dataset/`
+  (optionally with a `metadata.csv`); no code changes needed.
+* **Different difficulty calibration:** override `difficulty.*` weights/
+  thresholds in a config (must still sum to 1.0 — enforced by the schema).

annotations/bank_doc_01.json

@@ -0,0 +1,32 @@
+{
+  "id": "bank_doc_01",
+  "source_image": "image/guarantee/image copy 2.png",
+  "document_type": "bank_letter_of_guarantee",
+  "pages": [
+    {
+      "page": 1,
+      "page_size": [791, 1024],
+      "dpi": 300,
+      "signature_boxes": [
+        {
+          "id": "sig1",
+          "x1": 118,
+          "y1": 493,
+          "x2": 396,
+          "y2": 508,
+          "role": "Bank Officer",
+          "name": "Bank Officer"
+        },
+        {
+          "id": "sig2",
+          "x1": 118,
+          "y1": 700,
+          "x2": 404,
+          "y2": 715,
+          "role": "Notary Public",
+          "name": "Notary Public"
+        }
+      ]
+    }
+  ]
+}

annotations/bank_doc_02.json

@@ -0,0 +1,23 @@
+{
+  "id": "bank_doc_02",
+  "source_image": "image/guarantee/image copy.png",
+  "document_type": "bank_letter_of_guarantee",
+  "pages": [
+    {
+      "page": 1,
+      "page_size": [1024, 559],
+      "dpi": 300,
+      "signature_boxes": [
+        {
+          "id": "sig1",
+          "x1": 150,
+          "y1": 434,
+          "x2": 420,
+          "y2": 458,
+          "role": "Bank Representative",
+          "name": "Michael Chen"
+        }
+      ]
+    }
+  ]
+}

annotations/bank_doc_03.json

@@ -0,0 +1,32 @@
+{
+  "id": "bank_doc_03",
+  "source_image": "image/guarantee/image.png",
+  "document_type": "deed_of_guarantee",
+  "pages": [
+    {
+      "page": 1,
+      "page_size": [1024, 559],
+      "dpi": 300,
+      "signature_boxes": [
+        {
+          "id": "sig1",
+          "x1": 595,
+          "y1": 399,
+          "x2": 748,
+          "y2": 431,
+          "role": "Guarantor (Authorized Signatory)",
+          "name": "Guarantor"
+        },
+        {
+          "id": "sig2",
+          "x1": 805,
+          "y1": 399,
+          "x2": 955,
+          "y2": 431,
+          "role": "Bank Representative",
+          "name": "Lender"
+        }
+      ]
+    }
+  ]
+}

annotations/bank_doc_04.json

@@ -0,0 +1,32 @@
+{
+  "id": "bank_doc_04",
+  "source_image": "image/loan_forms/image copy 2.png",
+  "document_type": "corporate_bank_loan_agreement",
+  "pages": [
+    {
+      "page": 1,
+      "page_size": [1024, 559],
+      "dpi": 300,
+      "signature_boxes": [
+        {
+          "id": "sig1",
+          "x1": 580,
+          "y1": 435,
+          "x2": 750,
+          "y2": 475,
+          "role": "Borrower (Authorized Signatory)",
+          "name": "Borrower"
+        },
+        {
+          "id": "sig2",
+          "x1": 795,
+          "y1": 435,
+          "x2": 960,
+          "y2": 475,
+          "role": "Bank Representative",
+          "name": "Lender"
+        }
+      ]
+    }
+  ]
+}

annotations/bank_doc_05.json

@@ -0,0 +1,32 @@
+{
+  "id": "bank_doc_05",
+  "source_image": "image/loan_forms/image copy.png",
+  "document_type": "corporate_bank_loan_agreement",
+  "pages": [
+    {
+      "page": 1,
+      "page_size": [687, 1024],
+      "dpi": 300,
+      "signature_boxes": [
+        {
+          "id": "sig1",
+          "x1": 65,
+          "y1": 780,
+          "x2": 320,
+          "y2": 815,
+          "role": "Borrower",
+          "name": "Borrower"
+        },
+        {
+          "id": "sig2",
+          "x1": 370,
+          "y1": 780,
+          "x2": 625,
+          "y2": 815,
+          "role": "Authorized Signatory",
+          "name": "Lender"
+        }
+      ]
+    }
+  ]
+}

annotations/bank_doc_06.json

@@ -0,0 +1,32 @@
+{
+  "id": "bank_doc_06",
+  "source_image": "image/loan_forms/image.png",
+  "document_type": "corporate_bank_loan_agreement",
+  "pages": [
+    {
+      "page": 1,
+      "page_size": [1024, 559],
+      "dpi": 300,
+      "signature_boxes": [
+        {
+          "id": "sig1",
+          "x1": 90,
+          "y1": 421,
+          "x2": 345,
+          "y2": 433,
+          "role": "Borrower (Authorized Signatory)",
+          "name": "Borrower"
+        },
+        {
+          "id": "sig2",
+          "x1": 590,
+          "y1": 421,
+          "x2": 845,
+          "y2": 433,
+          "role": "Bank Representative",
+          "name": "Lender"
+        }
+      ]
+    }
+  ]
+}

annotations/bank_doc_07.json

@@ -0,0 +1,32 @@
+{
+  "id": "bank_doc_07",
+  "source_image": "image/mandate/image copy 2.png",
+  "document_type": "bank_mandate_attestation",
+  "pages": [
+    {
+      "page": 1,
+      "page_size": [1024, 1536],
+      "dpi": 300,
+      "signature_boxes": [
+        {
+          "id": "sig1",
+          "x1": 535,
+          "y1": 918,
+          "x2": 935,
+          "y2": 935,
+          "role": "Account Holder",
+          "name": "Account Holder"
+        },
+        {
+          "id": "sig2",
+          "x1": 345,
+          "y1": 973,
+          "x2": 700,
+          "y2": 990,
+          "role": "Bank Manager",
+          "name": "Bank Manager"
+        }
+      ]
+    }
+  ]
+}

annotations/bank_doc_08.json

@@ -0,0 +1,32 @@
+{
+  "id": "bank_doc_08",
+  "source_image": "image/mandate/image copy.png",
+  "document_type": "bank_account_verification_mandate",
+  "pages": [
+    {
+      "page": 1,
+      "page_size": [1024, 1536],
+      "dpi": 300,
+      "signature_boxes": [
+        {
+          "id": "sig1",
+          "x1": 345,
+          "y1": 672,
+          "x2": 495,
+          "y2": 696,
+          "role": "Account Holder",
+          "name": "Account Holder"
+        },
+        {
+          "id": "sig2",
+          "x1": 685,
+          "y1": 568,
+          "x2": 935,
+          "y2": 590,
+          "role": "Bank Manager",
+          "name": "Bank Manager"
+        }
+      ]
+    }
+  ]
+}

annotations/bank_doc_09.json

@@ -0,0 +1,32 @@
+{
+  "id": "bank_doc_09",
+  "source_image": "image/mandate/image.png",
+  "document_type": "corporate_account_opening_mandate",
+  "pages": [
+    {
+      "page": 1,
+      "page_size": [687, 1024],
+      "dpi": 300,
+      "signature_boxes": [
+        {
+          "id": "sig1",
+          "x1": 90,
+          "y1": 770,
+          "x2": 315,
+          "y2": 805,
+          "role": "First Authorised Signatory",
+          "name": "First Authorised Signatory"
+        },
+        {
+          "id": "sig2",
+          "x1": 350,
+          "y1": 770,
+          "x2": 575,
+          "y2": 805,
+          "role": "Second Authorised Signatory",
+          "name": "Second Authorised Signatory"
+        }
+      ]
+    }
+  ]
+}

configs/default.yaml

@@ -0,0 +1,216 @@
+# Base configuration for the synthetic signed bank document generator.
+#
+# This file defines every default value used by src.config.schema.PipelineConfig.
+# User configs (see configs/generate.yaml, configs/examples/*.yaml) are merged
+# on top of this file, so they only need to specify what they want to change.
+#
+# Any numeric placement/augmentation "strength"-like value may be given either
+# as a fixed scalar (e.g. `0.4`) or as a range (e.g. `{min: 0.2, max: 0.6}`),
+# which is resolved by a seeded RNG independently for every generated sample.
+
+seed: 1234
+
+paths:
+  image_dir: image
+  dataset_dir: dataset
+  annotations_dir: annotations
+  output_dir: output
+  cache_dir: output/.cache
+
+generation:
+  count: 10
+  workers: 1
+  save_visualization: false
+  overwrite: false
+  run_validation: true
+  start_index: 1
+  filename_prefix: sample
+  filename_digits: 6
+
+document:
+  template: null   # null = pick uniformly at random (deterministically, via seed)
+  page: null       # null = use the template's first page
+
+signer:
+  name: null       # null = generate a deterministic synthetic name
+  role: null       # null = use the signature box's annotated role
+
+signature_selection:
+  source_filter: genuine   # genuine | forged | any
+  signature_id: null       # null = pick uniformly at random from the filtered pool
+
+placement:
+  x_offset: 0.0
+  y_offset: 0.0
+  rotation_deg:
+    min: -4.0
+    max: 4.0
+  scale_factor:
+    min: 0.78
+    max: 0.95
+  anchor_point: center
+  margin: 0.08
+  misplacement_probability: 0.12
+  misplacement_strength: 0.35
+  allow_partial_outside: false
+
+rendering:
+  blend_mode: multiply
+  ink_opacity:
+    min: 0.75
+    max: 0.95
+  blur_sigma:
+    min: 0.15
+    max: 0.55
+  feather_px:
+    min: 0.5
+    max: 1.8
+  scanner_noise: 0.02
+  anti_alias: true
+
+augmentation:
+  rotation:
+    enabled: false
+    strength: 0.0
+    probability: 0.0
+    seed: null
+
+  stroke_dilation:
+    enabled: false
+    strength: 0.2
+    probability: 0.25
+    seed: null
+
+  motion_blur:
+    enabled: false
+    strength: 0.2
+    probability: 0.15
+    seed: null
+
+  gaussian_blur:
+    enabled: true
+    strength: 0.15
+    probability: 0.3
+    seed: null
+
+  perspective:
+    enabled: false
+    strength: 0.1
+    probability: 0.1
+    seed: null
+
+  scanner_noise:
+    enabled: true
+    strength: 0.06
+    probability: 1.0
+    seed: null
+
+  salt_pepper:
+    enabled: false
+    strength: 0.03
+    probability: 0.15
+    seed: null
+
+  jpeg_compression:
+    enabled: true
+    strength: 0.3
+    probability: 0.5
+    seed: null
+    min_quality: 35
+    max_quality: 90
+
+  contrast:
+    enabled: true
+    strength: 0.15
+    probability: 0.4
+    seed: null
+
+  gamma:
+    enabled: false
+    strength: 0.15
+    probability: 0.2
+    seed: null
+
+  coffee_stain:
+    enabled: false
+    strength: 0.4
+    probability: 0.1
+    seed: null
+
+  stain:
+    enabled: false
+    strength: 0.4
+    probability: 0.1
+    seed: null
+    type: random
+
+  shadow:
+    enabled: true
+    strength: 0.35
+    probability: 0.4
+    seed: null
+    type: random
+
+  crumple:
+    enabled: false
+    strength: 0.2
+    probability: 0.15
+    seed: null
+    wrinkle_density: 0.4
+
+  discoloration:
+    enabled: true
+    strength: 0.2
+    probability: 0.5
+    seed: null
+    tone: random
+
+  page_tilt:
+    enabled: true
+    strength: 0.3
+    probability: 0.3
+    seed: null
+
+  dust:
+    enabled: false
+    strength: 0.2
+    probability: 0.2
+    seed: null
+
+  scanner_streaks:
+    enabled: false
+    strength: 0.2
+    probability: 0.1
+    seed: null
+
+  ink_fading:
+    enabled: false
+    strength: 0.3
+    probability: 0.2
+    seed: null
+
+  ink_bleed:
+    enabled: false
+    strength: 0.25
+    probability: 0.15
+    seed: null
+
+quality:
+  case_type: null
+  notes: null
+  scanner_quality: 0.85
+  paper_quality: 0.85
+  render_quality: 0.85
+
+difficulty:
+  misplacement: 0.35
+  whitespace: 0.20
+  faintness: 0.20
+  smallness: 0.15
+  low_texture: 0.10
+  easy_threshold: 0.33
+  hard_threshold: 0.66
+
+validation:
+  strict: false
+  max_coordinate_epsilon: 0.5

configs/examples/clean_easy.yaml

@@ -0,0 +1,31 @@
+# A "mostly easy" dataset preset: well-centered signatures, minimal
+# degradation. Useful for a sanity-check baseline or an "easy" evaluation
+# split.
+#
+#   python main.py --config configs/examples/clean_easy.yaml --count 500
+
+seed: 1000
+
+generation:
+  count: 500
+  workers: 4
+
+placement:
+  scale_factor: { min: 0.85, max: 0.98 }
+  rotation_deg: { min: -1.5, max: 1.5 }
+  margin: 0.1
+  misplacement_probability: 0.0
+  allow_partial_outside: false
+
+rendering:
+  ink_opacity: { min: 0.85, max: 0.98 }
+  blur_sigma: { min: 0.1, max: 0.25 }
+  scanner_noise: 0.01
+
+augmentation:
+  gaussian_blur: { enabled: false }
+  shadow: { enabled: false }
+  discoloration: { enabled: false }
+  page_tilt: { enabled: true, strength: 0.1, probability: 0.15 }
+  scanner_noise: { enabled: true, strength: 0.02, probability: 1.0 }
+  jpeg_compression: { enabled: true, strength: 0.15, probability: 0.3, min_quality: 80, max_quality: 95 }

configs/examples/hard_degraded.yaml

@@ -0,0 +1,47 @@
+# A "mostly hard" dataset preset: frequent misplacement, faint ink, heavy
+# scanner/paper degradation. Useful for stress-testing a downstream
+# detector/verifier or building a "hard" evaluation split.
+#
+#   python main.py --config configs/examples/hard_degraded.yaml --count 500
+
+seed: 9001
+
+generation:
+  count: 500
+  workers: 4
+
+quality:
+  case_type: "1d"
+  notes: "low-quality scan, batch 9001"
+
+placement:
+  scale_factor: { min: 0.35, max: 0.7 }
+  rotation_deg: { min: -12.0, max: 12.0 }
+  margin: 0.04
+  misplacement_probability: 0.45
+  misplacement_strength: { min: 0.3, max: 0.8 }
+  allow_partial_outside: true
+
+rendering:
+  ink_opacity: { min: 0.35, max: 0.65 }
+  blur_sigma: { min: 0.6, max: 1.4 }
+  feather_px: { min: 1.5, max: 3.0 }
+  scanner_noise: 0.05
+
+augmentation:
+  ink_fading: { enabled: true, strength: { min: 0.4, max: 0.8 }, probability: 0.5 }
+  motion_blur: { enabled: true, strength: { min: 0.3, max: 0.6 }, probability: 0.3 }
+  perspective: { enabled: true, strength: { min: 0.15, max: 0.3 }, probability: 0.3 }
+  coffee_stain: { enabled: true, strength: { min: 0.4, max: 0.8 }, probability: 0.25 }
+  stain: { enabled: true, strength: { min: 0.4, max: 0.8 }, probability: 0.3, type: random }
+  shadow: { enabled: true, strength: { min: 0.5, max: 0.9 }, probability: 0.6, type: random }
+  crumple: { enabled: true, strength: { min: 0.4, max: 0.8 }, probability: 0.4 }
+  discoloration: { enabled: true, strength: { min: 0.4, max: 0.7 }, probability: 0.7, tone: random }
+  page_tilt: { enabled: true, strength: { min: 0.5, max: 1.0 }, probability: 0.5 }
+  dust: { enabled: true, strength: { min: 0.3, max: 0.7 }, probability: 0.4 }
+  scanner_streaks: { enabled: true, strength: { min: 0.3, max: 0.6 }, probability: 0.3 }
+  salt_pepper: { enabled: true, strength: { min: 0.03, max: 0.09 }, probability: 0.35 }
+  jpeg_compression: { enabled: true, strength: 0.7, probability: 0.7, min_quality: 20, max_quality: 55 }
+
+validation:
+  strict: false

configs/examples/single_document_demo.yaml

@@ -0,0 +1,50 @@
+# Demonstrates every "single value or range" knob on one fixed template with
+# a fixed signer identity -- handy for iterating on how one specific
+# document/box combination looks before scaling up to a full batch run.
+#
+#   python main.py --config configs/examples/single_document_demo.yaml --count 1
+
+seed: 4242
+
+document:
+  template: bank_doc_03
+
+signer:
+  name: Jane Doe
+  role: Branch Manager
+
+signature_selection:
+  source_filter: genuine
+
+placement:
+  scale_factor: 0.84
+  rotation_deg: -3.0
+  x_offset: 8.0
+  y_offset: -4.0
+  misplacement_probability: 0.32
+
+generation:
+  count: 1
+  save_visualization: true
+
+augmentation:
+  coffee_stain:
+    enabled: true
+    strength: 0.42
+    probability: 1.0
+
+  shadow:
+    enabled: true
+    strength: 0.55
+    probability: 1.0
+    type: corner
+
+  crumple:
+    enabled: true
+    strength: 0.18
+    probability: 1.0
+
+  scanner_noise:
+    enabled: true
+    strength: 0.06
+    probability: 1.0

configs/examples/verification_cases.yaml

@@ -0,0 +1,34 @@
+# Signature-verification test-case generation. Set quality.case_type to one
+# of the 12 codes below to switch GeneratorContext into scenario-driven
+# generation: it renders the described scenario and stamps the sample's
+# metadata `verification` block with the matching ground-truth verdict/
+# reject_code. Left unset (the default), generation is completely unaffected.
+#
+#   python main.py --config configs/examples/verification_cases.yaml \
+#       --set quality.case_type=3a --count 10
+#
+# For "1d" (correct signer, but the scan itself is degraded) use
+# configs/examples/hard_degraded.yaml instead -- it already sets
+# `quality.case_type: "1d"` plus the matching degraded-scan overrides; this
+# file's job is everything else, where a clean/legible scan is expected.
+#
+# | code | scenario                                            | verdict | reject_code            |
+# |------|------------------------------------------------------|---------|-------------------------|
+# | 1a   | Correct signer signs normally                         | PASS    | -                       |
+# | 1b   | Correct signer, natural pen variation                 | PASS    | -                       |
+# | 1c   | Multi-signer form, both sign correctly                | PASS    | -                       |
+# | 1d   | Correct signer, scan degraded (see hard_degraded.yaml)| PASS    | -                       |
+# | 2a   | Box left completely blank                             | REJECT  | NO_SIGNATURE            |
+# | 2b   | Printed/typed name only, no handwriting               | REJECT  | NO_SIGNATURE            |
+# | 3a   | Wrong real person signs the box                       | REJECT  | IDENTITY_MISMATCH       |
+# | 3b   | Skilled-forgery sample used                           | REJECT  | IDENTITY_MISMATCH       |
+# | 4a   | Authorized signer, but wrong role's box               | REJECT  | ROLE_MISMATCH           |
+# | 4b   | Signer from a different form entirely                 | REJECT  | ROLE_MISMATCH           |
+# | 5a   | Required signer's box left empty                      | REJECT  | REQUIRED_SIGNER_ABSENT  |
+# | 5b   | Someone else signs in the required signer's place     | REJECT  | REQUIRED_SIGNER_ABSENT  |
+
+quality:
+  case_type: "1a"   # <- override with --set quality.case_type=<code>
+
+validation:
+  strict: false

configs/generate.yaml

@@ -0,0 +1,171 @@
+# Example large-batch dataset generation config.
+#
+# Merged on top of configs/default.yaml. Only values that differ from the
+# defaults need to be listed here. Run with:
+#
+#   python main.py --config configs/generate.yaml --count 10000
+#
+# (--count on the command line overrides generation.count below.)
+
+seed: 20240601
+
+paths:
+  output_dir: output
+
+generation:
+  count: 2000
+  workers: 4
+  save_visualization: false
+  overwrite: false
+  run_validation: true
+
+# document.template left as null -> every sample independently and
+# deterministically picks one of the 9 discovered templates.
+document:
+  template: null
+
+# signer.name/role left as null -> a synthetic name is generated per sample
+# and the role is taken from the chosen signature box's annotation.
+signer:
+  name: null
+  role: null
+
+signature_selection:
+  source_filter: genuine
+
+placement:
+  scale_factor:
+    min: 0.75
+    max: 0.98
+  rotation_deg:
+    min: -6.0
+    max: 6.0
+  margin: 0.07
+  misplacement_probability: 0.15
+  misplacement_strength:
+    min: 0.15
+    max: 0.5
+  allow_partial_outside: true
+
+rendering:
+  blend_mode: multiply
+  ink_opacity:
+    min: 0.7
+    max: 0.97
+  blur_sigma:
+    min: 0.15
+    max: 0.6
+  feather_px:
+    min: 0.4
+    max: 2.0
+  scanner_noise: 0.02
+
+augmentation:
+  stroke_dilation:
+    enabled: true
+    strength: { min: 0.1, max: 0.35 }
+    probability: 0.2
+
+  gaussian_blur:
+    enabled: true
+    strength: { min: 0.05, max: 0.3 }
+    probability: 0.3
+
+  motion_blur:
+    enabled: true
+    strength: { min: 0.1, max: 0.35 }
+    probability: 0.12
+
+  ink_fading:
+    enabled: true
+    strength: { min: 0.1, max: 0.5 }
+    probability: 0.2
+
+  ink_bleed:
+    enabled: true
+    strength: { min: 0.1, max: 0.4 }
+    probability: 0.15
+
+  perspective:
+    enabled: true
+    strength: { min: 0.05, max: 0.2 }
+    probability: 0.12
+
+  contrast:
+    enabled: true
+    strength: { min: 0.05, max: 0.3 }
+    probability: 0.4
+
+  gamma:
+    enabled: true
+    strength: { min: 0.05, max: 0.25 }
+    probability: 0.2
+
+  coffee_stain:
+    enabled: true
+    strength: { min: 0.2, max: 0.6 }
+    probability: 0.08
+
+  stain:
+    enabled: true
+    strength: { min: 0.2, max: 0.6 }
+    probability: 0.1
+    type: random
+
+  shadow:
+    enabled: true
+    strength: { min: 0.2, max: 0.6 }
+    probability: 0.35
+    type: random
+
+  crumple:
+    enabled: true
+    strength: { min: 0.1, max: 0.4 }
+    probability: 0.12
+    wrinkle_density: { min: 0.2, max: 0.7 }
+
+  discoloration:
+    enabled: true
+    strength: { min: 0.1, max: 0.4 }
+    probability: 0.45
+    tone: random
+
+  page_tilt:
+    enabled: true
+    strength: { min: 0.1, max: 0.5 }
+    probability: 0.3
+
+  dust:
+    enabled: true
+    strength: { min: 0.1, max: 0.4 }
+    probability: 0.2
+
+  scanner_streaks:
+    enabled: true
+    strength: { min: 0.1, max: 0.35 }
+    probability: 0.1
+
+  scanner_noise:
+    enabled: true
+    strength: { min: 0.02, max: 0.1 }
+    probability: 1.0
+
+  salt_pepper:
+    enabled: true
+    strength: { min: 0.01, max: 0.06 }
+    probability: 0.15
+
+  jpeg_compression:
+    enabled: true
+    strength: { min: 0.2, max: 0.6 }
+    probability: 0.5
+    min_quality: 40
+    max_quality: 92
+
+quality:
+  scanner_quality: { min: 0.6, max: 0.98 }
+  paper_quality: { min: 0.6, max: 0.98 }
+  render_quality: { min: 0.6, max: 0.98 }
+
+validation:
+  strict: false

dataset/metadata.csv

@@ -0,0 +1,12 @@
+path,signer,source_type,script
+hindi_bengali/priya_ref01.png,Priya Sharma,genuine,hindi
+hindi_bengali/raj_ref01.png,Raj Malhotra,genuine,hindi
+hindi_bengali/raj_ref03.png,Raj Malhotra,genuine,hindi
+hindi_bengali/vikram_ref01.png,Vikram Singh,genuine,hindi
+hindi_bengali/vikram_ref02.png,Vikram Singh,genuine,hindi
+hindi_bengali/vikram_ref03.png,Vikram Singh,genuine,hindi
+hindi_bengali/suman_ref01.png,Suman Das,genuine,bengali
+hindi_bengali/anika_ref01.png,Anika Roy,genuine,bengali
+hindi_bengali/anika_ref02.png,Anika Roy,genuine,bengali
+hindi_bengali/carol_ref01.png,Carol Wong,genuine,latin
+hindi_bengali/henry_ref01.png,Henry Ooi,genuine,latin

main.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python
+"""CLI entry point for the synthetic signed bank document generation pipeline.
+
+Examples:
+    Generate 10 samples with all defaults::
+
+        python main.py
+
+    Generate 10,000 samples using a custom config::
+
+        python main.py --config configs/generate.yaml --count 10000
+
+    Override arbitrary nested config values from the command line::
+
+        python main.py --set placement.rotation_deg.max=6 --set augmentation.coffee_stain.enabled=true
+
+    Generate a single, fully reproducible sample from one template with a debug figure::
+
+        python main.py --count 1 --seed 42 --template bank_doc_03 --save-visualization
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import sys
+from pathlib import Path
+
+from src.config.loader import load_config, save_resolved_config
+from src.generator import DatasetGenerator
+from src.utils.logging_utils import configure_logging, get_logger
+
+logger = get_logger(__name__)
+
+
+def build_arg_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Generate synthetic signed bank documents with rich ML-ready metadata.",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    parser.add_argument("--config", type=str, default=None, help="Path to a user YAML config, merged over configs/default.yaml.")
+    parser.add_argument("--count", type=int, default=None, help="Number of samples to generate (overrides config).")
+    parser.add_argument("--seed", type=int, default=None, help="Master random seed (overrides config).")
+    parser.add_argument("--workers", type=int, default=None, help="Number of worker processes (overrides config).")
+    parser.add_argument("--output", type=str, default=None, help="Output directory (overrides config).")
+    parser.add_argument("--template", type=str, default=None, help="Restrict generation to a single template id, e.g. bank_doc_03.")
+    parser.add_argument("--start-index", type=int, default=None, help="First sample index (overrides config).")
+    parser.add_argument("--overwrite", action="store_true", default=None, help="Regenerate samples even if their output files already exist.")
+    parser.add_argument("--save-visualization", action="store_true", default=None, help="Also save a debug visualization PNG per sample.")
+    parser.add_argument(
+        "--set", dest="overrides", action="append", default=[],
+        metavar="key.path=value", help="Arbitrary dot-path config override; may be repeated.",
+    )
+    parser.add_argument("--log-level", type=str, default="INFO", choices=["DEBUG", "INFO", "WARNING", "ERROR"])
+    return parser
+
+
+def _collect_overrides(args: argparse.Namespace) -> list[str]:
+    overrides = list(args.overrides)
+    if args.count is not None:
+        overrides.append(f"generation.count={args.count}")
+    if args.workers is not None:
+        overrides.append(f"generation.workers={args.workers}")
+    if args.output is not None:
+        overrides.append(f"paths.output_dir={args.output}")
+    if args.start_index is not None:
+        overrides.append(f"generation.start_index={args.start_index}")
+    if args.overwrite:
+        overrides.append("generation.overwrite=true")
+    if args.save_visualization:
+        overrides.append("generation.save_visualization=true")
+    if args.seed is not None:
+        overrides.append(f"seed={args.seed}")
+    if args.template is not None:
+        overrides.append(f"document.template={args.template}")
+    return overrides
+
+
+def main(argv: "list[str] | None" = None) -> int:
+    args = build_arg_parser().parse_args(argv)
+    configure_logging(level=getattr(logging, args.log_level))
+
+    overrides = _collect_overrides(args)
+    config = load_config(config_path=args.config, overrides=overrides)
+
+    logger.info("Starting generation: seed=%d, count=%d, workers=%d, output=%s",
+                config.seed, config.generation.count, config.generation.workers, config.paths.output_dir)
+
+    output_dir = Path(config.paths.output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    save_resolved_config(config, output_dir / "resolved_config.yaml")
+
+    generator = DatasetGenerator(config)
+    summary = generator.generate()
+
+    summary_path = output_dir / "generation_summary.json"
+    summary_path.write_text(json.dumps(summary.as_dict(), indent=2), encoding="utf-8")
+    logger.info("Wrote generation summary to %s", summary_path)
+    logger.info(
+        "Done: %d/%d succeeded, %d failed, %d skipped (already existed). Difficulty tiers: %s",
+        summary.succeeded, summary.total, summary.failed, summary.skipped_existing, summary.tier_counts,
+    )
+    if summary.validation_failed:
+        logger.warning("%d sample(s) failed validation.", summary.validation_failed)
+
+    return 1 if summary.failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pytest.ini

@@ -0,0 +1,4 @@
+[pytest]
+pythonpath = .
+testpaths = tests
+python_files = test_*.py

requirements.txt

@@ -0,0 +1,15 @@
+numpy>=1.26
+opencv-python>=4.9
+scipy>=1.12
+Pillow>=10.2
+scikit-image>=0.22
+Shapely>=2.0
+PyYAML>=6.0
+pydantic>=2.6
+albumentations>=1.4
+omegaconf>=2.3
+matplotlib>=3.8
+tqdm>=4.66
+pytest>=8.0
+rich>=13.7
+questionary>=2.0

src/config/__init__.py

@@ -0,0 +1,6 @@
+"""Configuration schema (Pydantic) and OmegaConf-based YAML loading."""
+
+from src.config.schema import PipelineConfig
+from src.config.loader import load_config
+
+__all__ = ["PipelineConfig", "load_config"]

src/config/schema.py

@@ -0,0 +1,267 @@
+"""Pydantic configuration schema for the synthetic document generation pipeline.
+
+Every user-facing parameter is validated here. Numeric placement/augmentation
+parameters accept either a fixed scalar or a ``{min, max}`` range (resolved
+per-sample by a seeded RNG, see :mod:`src.utils.random_utils`).
+
+The individual augmentation effects requested by the product spec are
+consolidated into configurable *families* where an effect is a strict
+specialization of another (paper stains + water stains -> ``stain`` with a
+``type`` selector; edge/corner/fold shadows -> ``shadow`` with a ``type``
+selector; crumpling + wrinkles -> ``crumple``; general discoloration + paper
+yellowing -> ``discoloration`` with a ``tone`` selector). This keeps the
+config surface coherent while still reaching every requested visual effect.
+"""
+
+from __future__ import annotations
+
+from typing import Literal, Union
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+NumericOrRange_T = Union[float, "Range"]
+
+
+class Range(BaseModel):
+    """An inclusive ``[min, max]`` range a value is uniformly sampled from."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    min: float
+    max: float
+
+    @model_validator(mode="after")
+    def _check_order(self) -> "Range":
+        if self.max < self.min:
+            raise ValueError(f"Range max ({self.max}) must be >= min ({self.min})")
+        return self
+
+
+NumericOrRange = Union[float, Range]
+
+
+class AugmentationParam(BaseModel):
+    """Base schema shared by every augmentation effect.
+
+    Extra keys are allowed so effect-specific parameters (e.g. ``type`` for
+    :class:`ShadowParam`, ``tone`` for discoloration) can be declared inline
+    in YAML without needing a bespoke subclass for every single effect.
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    enabled: bool = False
+    strength: NumericOrRange = 0.0
+    probability: float = Field(default=1.0, ge=0.0, le=1.0)
+    seed: "int | None" = None
+
+    @field_validator("strength")
+    @classmethod
+    def _strength_bounds(cls, v: NumericOrRange) -> NumericOrRange:
+        if isinstance(v, (int, float)) and not (0.0 <= float(v) <= 1.0):
+            raise ValueError("strength must be within [0, 1]")
+        return v
+
+
+class ShadowParam(AugmentationParam):
+    type: Literal["edge", "corner", "fold", "random"] = "random"
+
+
+class StainParam(AugmentationParam):
+    type: Literal["paper", "water", "random"] = "random"
+
+
+class DiscolorationParam(AugmentationParam):
+    tone: Literal["yellow", "grey", "sepia", "random"] = "random"
+
+
+class CrumpleParam(AugmentationParam):
+    wrinkle_density: NumericOrRange = 0.4
+
+
+class JpegCompressionParam(AugmentationParam):
+    min_quality: int = Field(default=35, ge=1, le=100)
+    max_quality: int = Field(default=90, ge=1, le=100)
+
+
+class AugmentationsConfig(BaseModel):
+    """The full family of configurable document/signature augmentations."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    rotation: AugmentationParam = Field(default_factory=lambda: AugmentationParam())
+    stroke_dilation: AugmentationParam = Field(default_factory=lambda: AugmentationParam())
+    motion_blur: AugmentationParam = Field(default_factory=lambda: AugmentationParam())
+    gaussian_blur: AugmentationParam = Field(default_factory=lambda: AugmentationParam())
+    perspective: AugmentationParam = Field(default_factory=lambda: AugmentationParam())
+    scanner_noise: AugmentationParam = Field(default_factory=lambda: AugmentationParam(enabled=True, strength=0.06, probability=1.0))
+    salt_pepper: AugmentationParam = Field(default_factory=lambda: AugmentationParam())
+    jpeg_compression: JpegCompressionParam = Field(default_factory=lambda: JpegCompressionParam())
+    contrast: AugmentationParam = Field(default_factory=lambda: AugmentationParam())
+    gamma: AugmentationParam = Field(default_factory=lambda: AugmentationParam())
+    coffee_stain: AugmentationParam = Field(default_factory=lambda: AugmentationParam())
+    stain: StainParam = Field(default_factory=lambda: StainParam())
+    shadow: ShadowParam = Field(default_factory=lambda: ShadowParam())
+    crumple: CrumpleParam = Field(default_factory=lambda: CrumpleParam())
+    discoloration: DiscolorationParam = Field(default_factory=lambda: DiscolorationParam())
+    page_tilt: AugmentationParam = Field(default_factory=lambda: AugmentationParam())
+    dust: AugmentationParam = Field(default_factory=lambda: AugmentationParam())
+    scanner_streaks: AugmentationParam = Field(default_factory=lambda: AugmentationParam())
+    ink_fading: AugmentationParam = Field(default_factory=lambda: AugmentationParam())
+    ink_bleed: AugmentationParam = Field(default_factory=lambda: AugmentationParam())
+
+    def items(self):
+        """Yield ``(name, AugmentationParam)`` pairs for every configured effect."""
+        for name in self.model_fields:
+            yield name, getattr(self, name)
+
+
+class PlacementConfig(BaseModel):
+    """Controls where and how the signature is positioned inside its target box."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    x_offset: NumericOrRange = 0.0
+    y_offset: NumericOrRange = 0.0
+    rotation_deg: NumericOrRange = 0.0
+    scale_factor: NumericOrRange = 0.9
+    anchor_point: Literal[
+        "center", "top_left", "top_right", "bottom_left", "bottom_right",
+        "top_center", "bottom_center", "left_center", "right_center",
+    ] = "center"
+    margin: float = Field(default=0.06, ge=0.0, le=0.45)
+    misplacement_probability: float = Field(default=0.0, ge=0.0, le=1.0)
+    misplacement_strength: NumericOrRange = 0.3
+    allow_partial_outside: bool = False
+
+
+class RenderingConfig(BaseModel):
+    """Controls how the signature layer is composited onto the document."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    blend_mode: Literal["multiply", "darken", "alpha"] = "multiply"
+    ink_opacity: NumericOrRange = 0.88
+    blur_sigma: NumericOrRange = 0.35
+    feather_px: NumericOrRange = 1.2
+    scanner_noise: NumericOrRange = 0.02
+    anti_alias: bool = True
+
+
+class SignerConfig(BaseModel):
+    """Optional overrides for the assigned signer identity."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: "str | None" = None
+    role: "str | None" = None
+
+
+class SignatureSelectionConfig(BaseModel):
+    """Controls how a signature image is drawn from the discovered dataset."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    source_filter: Literal["genuine", "forged", "any"] = "genuine"
+    signature_id: "str | None" = None
+
+
+class DocumentConfig(BaseModel):
+    """Selects which template (and page) to render."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    template: "str | None" = None
+    page: "int | None" = None
+
+
+class QualityConfig(BaseModel):
+    """Document quality-flag inputs (feed into the ``quality`` metadata block)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    case_type: "str | None" = None
+    notes: "str | None" = None
+    scanner_quality: NumericOrRange = 0.85
+    paper_quality: NumericOrRange = 0.85
+    render_quality: NumericOrRange = 0.85
+
+
+class DifficultyWeights(BaseModel):
+    """Weights and tier thresholds for the difficulty score.
+
+    Defaults match the specification exactly:
+    ``0.35*misplacement + 0.20*whitespace + 0.20*faintness + 0.15*smallness + 0.10*low_texture``.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    misplacement: float = 0.35
+    whitespace: float = 0.20
+    faintness: float = 0.20
+    smallness: float = 0.15
+    low_texture: float = 0.10
+    easy_threshold: float = 0.33
+    hard_threshold: float = 0.66
+
+    @model_validator(mode="after")
+    def _check_weights(self) -> "DifficultyWeights":
+        total = self.misplacement + self.whitespace + self.faintness + self.smallness + self.low_texture
+        if abs(total - 1.0) > 1e-6:
+            raise ValueError(f"Difficulty weights must sum to 1.0, got {total}")
+        return self
+
+
+class PathsConfig(BaseModel):
+    """Filesystem locations for inputs/outputs."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    image_dir: str = "image"
+    dataset_dir: str = "dataset"
+    annotations_dir: str = "annotations"
+    output_dir: str = "output"
+    cache_dir: str = "output/.cache"
+
+
+class GenerationConfig(BaseModel):
+    """Batch-generation controls."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    count: int = Field(default=10, ge=1)
+    workers: int = Field(default=1, ge=1)
+    save_visualization: bool = False
+    overwrite: bool = False
+    run_validation: bool = True
+    start_index: int = Field(default=1, ge=0)
+    filename_prefix: str = "sample"
+    filename_digits: int = Field(default=6, ge=1)
+
+
+class ValidationConfig(BaseModel):
+    """Controls strictness of the post-generation ValidationEngine."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    strict: bool = False
+    max_coordinate_epsilon: float = 0.5
+
+
+class PipelineConfig(BaseModel):
+    """Top-level configuration for a full generation run."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    seed: int = 1234
+    paths: PathsConfig = Field(default_factory=PathsConfig)
+    generation: GenerationConfig = Field(default_factory=GenerationConfig)
+    document: DocumentConfig = Field(default_factory=DocumentConfig)
+    signer: SignerConfig = Field(default_factory=SignerConfig)
+    signature_selection: SignatureSelectionConfig = Field(default_factory=SignatureSelectionConfig)
+    placement: PlacementConfig = Field(default_factory=PlacementConfig)
+    rendering: RenderingConfig = Field(default_factory=RenderingConfig)
+    augmentation: AugmentationsConfig = Field(default_factory=AugmentationsConfig)
+    quality: QualityConfig = Field(default_factory=QualityConfig)
+    difficulty: DifficultyWeights = Field(default_factory=DifficultyWeights)
+    validation: ValidationConfig = Field(default_factory=ValidationConfig)

src/metadata/__init__.py

@@ -0,0 +1 @@
+"""Metadata assembly and export."""

src/metadata/metadata_exporter.py

@@ -0,0 +1,234 @@
+"""Assembles and writes the complete per-sample metadata JSON.
+
+The exported schema always includes every documented field -- augmentation
+parameters that were not applied are still present, with a neutral value
+(``0``/``null``/``false``) rather than being omitted, so downstream
+consumers can rely on a stable schema across the whole dataset.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from src.analysis.difficulty_analyzer import DifficultyResult
+from src.analysis.geometry_analyzer import GeometryResult
+from src.augmentation.augmentation_engine import AugmentationRecord
+from src.config.schema import QualityConfig
+from src.placement.placement_engine import PlacementResult
+from src.rendering.renderer import RenderResult
+from src.signatures.signature_dataset import SignatureRecord
+from src.utils.logging_utils import get_logger
+
+logger = get_logger(__name__)
+
+
+def _json_default(obj: Any) -> Any:
+    if isinstance(obj, np.integer):
+        return int(obj)
+    if isinstance(obj, np.floating):
+        return float(obj)
+    if isinstance(obj, np.bool_):
+        return bool(obj)
+    if isinstance(obj, np.ndarray):
+        return obj.tolist()
+    if isinstance(obj, Path):
+        return obj.as_posix()
+    return str(obj)
+
+
+class MetadataExporter:
+    """Builds and writes the full per-sample metadata JSON document.
+
+    Example:
+        >>> exporter = MetadataExporter()
+        >>> metadata = exporter.build(...)
+        >>> exporter.export(metadata, "output/sample_000001.json")
+    """
+
+    def build(
+        self,
+        document_id: str,
+        template_id: str,
+        document_type: "str | None",
+        page: int,
+        page_size: tuple[int, int],
+        dpi: int,
+        signer_name: str,
+        signer_role: str,
+        signature_source: "SignatureRecord | None",
+        placement: PlacementResult,
+        render: RenderResult,
+        signature_aug: dict[str, AugmentationRecord],
+        document_aug: dict[str, AugmentationRecord],
+        geometry: GeometryResult,
+        difficulty: DifficultyResult,
+        quality_cfg: QualityConfig,
+        quality_values: dict[str, float],
+        seed: int,
+        sample_index: int,
+        verification: "dict[str, Any] | None" = None,
+    ) -> dict[str, Any]:
+        """Assemble the complete metadata dict for one generated sample."""
+        degraded = self._compute_degraded(quality_cfg)
+
+        augmentation_section = self._build_augmentation_section(placement, render, signature_aug, document_aug)
+
+        metadata: dict[str, Any] = {
+            "document_id": document_id,
+            "template": template_id,
+            "document_type": document_type,
+            "page": page,
+            "page_size": list(page_size),
+            "dpi": dpi,
+            "signer": {
+                "name": signer_name,
+                "role": signer_role,
+            },
+            "signature_source": (
+                {
+                    "signature_id": signature_source.signature_id,
+                    "path": signature_source.path.as_posix(),
+                    "signer_group": signature_source.signer_group,
+                    "source_type": signature_source.source_type,
+                    "script": signature_source.script,
+                }
+                if signature_source is not None
+                else {"signature_id": None, "path": None, "signer_group": None, "source_type": "none", "script": None}
+            ),
+            "placement": {
+                "x_offset": placement.x_offset,
+                "y_offset": placement.y_offset,
+                "rotation_deg": round(placement.rotation_deg, 3),
+                "scale_factor": round(placement.scale_factor, 4),
+                "anchor_point": placement.anchor_point,
+                "margin_target_box": list(placement.target_box),
+                "misplaced": placement.misplaced,
+                "misplacement_dx": round(placement.misplacement_dx, 2),
+                "misplacement_dy": round(placement.misplacement_dy, 2),
+            },
+            "rendering": {
+                "blend_mode": render.blend_mode,
+                "ink_opacity": render.ink_opacity,
+                "blur_sigma": render.blur_sigma,
+                "feather_px": render.feather_px,
+                "scanner_noise": render.scanner_noise,
+            },
+            "difficulty": {
+                "score": difficulty.score,
+                "tier": difficulty.tier,
+                "misplacement": difficulty.misplacement,
+                "whitespace": difficulty.whitespace,
+                "faintness": difficulty.faintness,
+                "smallness": difficulty.smallness,
+                "low_texture": difficulty.low_texture,
+            },
+            "quality": {
+                "degraded": degraded,
+                "case_type": quality_cfg.case_type,
+                "notes": quality_cfg.notes,
+                "scanner_quality": quality_values["scanner_quality"],
+                "paper_quality": quality_values["paper_quality"],
+                "render_quality": quality_values["render_quality"],
+            },
+            "verification": verification or {
+                "case_type": None, "verdict": None, "reject_code": None,
+                "target_box_id": None, "expected_signer_group": None, "expected_signer_script": None,
+                "actual_signer_group": None, "actual_source_type": None, "actual_signer_script": None,
+                "companion": None,
+            },
+            "augmentation": augmentation_section,
+            "geometry": {
+                "box_px": list(geometry.target_box),
+                "signature_bbox_px": list(geometry.signature_bbox_px),
+                "target_box": list(geometry.target_box),
+                "actual_box": list(geometry.actual_box),
+                "search_box_px": list(geometry.search_box),
+                "signature_polygon_px": geometry.signature_polygon_px,
+                "convex_hull_px": geometry.convex_hull_px,
+                "min_rotated_rect": geometry.min_rotated_rect,
+                "centroid_px": list(geometry.centroid_px),
+                "orientation_deg": geometry.orientation_deg,
+                "ink_pixels": geometry.ink_pixels,
+                "detected": geometry.found,
+            },
+            "metrics": {
+                "box_coverage_pct": geometry.box_coverage_pct,
+                "containment_pct": geometry.containment_pct,
+                "ink_fill_ratio": geometry.ink_fill_ratio,
+                "polygon_overlap_proxy": geometry.polygon_overlap_proxy,
+                "distance_from_box_center_px": geometry.distance_from_box_center_px,
+                "margin_utilization": geometry.margin_utilization,
+                "mean_dark_intensity": geometry.mean_dark_intensity,
+                "gray_stddev": geometry.gray_stddev,
+                "signature_area_ratio": geometry.signature_area_ratio,
+            },
+            "provenance": {
+                "master_seed": seed,
+                "sample_index": sample_index,
+            },
+        }
+        return metadata
+
+    @staticmethod
+    def _compute_degraded(quality_cfg: QualityConfig) -> bool:
+        case_type_flag = quality_cfg.case_type == "1d"
+        notes_flag = bool(quality_cfg.notes and "low-quality" in quality_cfg.notes.lower())
+        return bool(case_type_flag or notes_flag)
+
+    @staticmethod
+    def _build_augmentation_section(
+        placement: PlacementResult, render: RenderResult,
+        signature_aug: dict[str, AugmentationRecord], document_aug: dict[str, AugmentationRecord],
+    ) -> dict[str, Any]:
+        def rec(records: dict[str, AugmentationRecord], name: str) -> AugmentationRecord:
+            return records[name]
+
+        stroke_rec = rec(signature_aug, "stroke_dilation")
+        noise_rec = rec(document_aug, "scanner_noise")
+        stain_rec = rec(document_aug, "stain")
+        shadow_rec = rec(document_aug, "shadow")
+        coffee_rec = rec(document_aug, "coffee_stain")
+        crumple_rec = rec(document_aug, "crumple")
+        tilt_rec = rec(document_aug, "page_tilt")
+        discoloration_rec = rec(document_aug, "discoloration")
+        jpeg_rec = rec(document_aug, "jpeg_compression")
+
+        effects: dict[str, Any] = {}
+        for name, r in {**signature_aug, **document_aug}.items():
+            effects[name] = {
+                "enabled": r.enabled,
+                "applied": r.applied,
+                "strength": r.strength,
+                "probability": r.probability,
+                "seed": r.seed,
+                "params": r.params,
+            }
+
+        return {
+            "rotate_deg": round(placement.rotation_deg, 3),
+            "scale_factor": round(placement.scale_factor, 4),
+            "stroke": stroke_rec.strength if stroke_rec.applied else 0.0,
+            "noise_amount": noise_rec.strength if noise_rec.applied else 0.0,
+            "stain_type": stain_rec.params.get("resolved_type") if stain_rec.applied else None,
+            "stain_strength": stain_rec.strength if stain_rec.applied else 0.0,
+            "shadow_type": shadow_rec.params.get("resolved_type") if shadow_rec.applied else None,
+            "shadow_strength": shadow_rec.strength if shadow_rec.applied else 0.0,
+            "coffee_stain_strength": coffee_rec.strength if coffee_rec.applied else 0.0,
+            "crumple_strength": crumple_rec.strength if crumple_rec.applied else 0.0,
+            "tilt_deg": tilt_rec.params.get("tilt_deg", 0.0) if tilt_rec.applied else 0.0,
+            "discoloration_strength": discoloration_rec.strength if discoloration_rec.applied else 0.0,
+            "blur_sigma": render.blur_sigma,
+            "jpeg_quality": jpeg_rec.params.get("quality") if jpeg_rec.applied else None,
+            "scanner_noise": render.scanner_noise,
+            "effects": effects,
+        }
+
+    def export(self, metadata: dict[str, Any], path: "str | Path") -> None:
+        """Write the metadata dict to disk as pretty-printed JSON."""
+        path = Path(path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(metadata, indent=2, default=_json_default), encoding="utf-8")

src/placement/__init__.py

@@ -0,0 +1 @@
+"""Signature placement: fitting, transforming, and positioning a signature stamp inside a target box."""

src/placement/placement_engine.py

@@ -0,0 +1,189 @@
+"""Places a preprocessed signature stamp inside (or intentionally near) a target signature box.
+
+Handles aspect-ratio-preserving scale-to-fit, rotation, anchor-based
+positioning, sub-pixel offsets, and controlled "misplacement" (an
+intentional, probability-gated extra translation used to generate
+hard/misaligned samples for benchmarking).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import cv2
+import numpy as np
+
+from src.config.schema import PlacementConfig
+from src.utils.geometry_utils import Box
+from src.utils.logging_utils import get_logger
+from src.utils.random_utils import SeedManager, resolve_scalar_or_range
+from src.utils.transform_utils import rotate_and_scale_rgba
+
+logger = get_logger(__name__)
+
+AnchorOffsetFn = "dict[str, callable]"
+
+MIN_SIGNATURE_HEIGHT_PX = 16.0
+
+
+@dataclass
+class PlacementResult:
+    """Everything downstream stages need to know about how the signature was placed."""
+
+    layer: np.ndarray  # full-canvas-sized RGBA layer, transparent outside the signature
+    target_box: Box
+    intended_bbox: Box  # the signature's transformed bounding box in canvas coordinates
+    x_offset: float
+    y_offset: float
+    rotation_deg: float
+    scale_factor: float
+    anchor_point: str
+    misplaced: bool
+    misplacement_dx: float
+    misplacement_dy: float
+
+
+def _anchor_top_left(anchor: str, box_w: float, box_h: float, sig_w: float, sig_h: float) -> tuple[float, float]:
+    positions = {
+        "center": ((box_w - sig_w) / 2.0, (box_h - sig_h) / 2.0),
+        "top_left": (0.0, 0.0),
+        "top_right": (box_w - sig_w, 0.0),
+        "bottom_left": (0.0, box_h - sig_h),
+        "bottom_right": (box_w - sig_w, box_h - sig_h),
+        "top_center": ((box_w - sig_w) / 2.0, 0.0),
+        "bottom_center": ((box_w - sig_w) / 2.0, box_h - sig_h),
+        "left_center": (0.0, (box_h - sig_h) / 2.0),
+        "right_center": (box_w - sig_w, (box_h - sig_h) / 2.0),
+    }
+    return positions.get(anchor, positions["center"])
+
+
+class PlacementEngine:
+    """Fits, transforms, and positions a signature stamp relative to a target box.
+
+    Example:
+        >>> engine = PlacementEngine(cfg.placement)
+        >>> result = engine.place(signature_rgba, target_box=(100, 100, 300, 160),
+        ...                       canvas_size=(1024, 559), seed_manager=sm)
+    """
+
+    def __init__(self, config: PlacementConfig) -> None:
+        self.config = config
+
+    def place(
+        self,
+        signature_rgba: np.ndarray,
+        target_box: Box,
+        canvas_size: tuple[int, int],
+        seed_manager: SeedManager,
+    ) -> PlacementResult:
+        """Compute the placed signature layer for one sample.
+
+        Args:
+            signature_rgba: The tightly-cropped RGBA signature stamp from
+                :class:`~src.rendering.signature_preprocessor.SignaturePreprocessor`.
+            target_box: The ``(x1, y1, x2, y2)`` target signature field, in
+                canvas pixel coordinates.
+            canvas_size: ``(width, height)`` of the full document canvas.
+            seed_manager: Per-sample deterministic RNG provider.
+
+        Returns:
+            A :class:`PlacementResult` with the full-canvas RGBA layer ready
+            for blending, plus every resolved placement parameter for
+            metadata export.
+        """
+        cfg = self.config
+        rng = seed_manager.numpy_rng("placement")
+        canvas_w, canvas_h = canvas_size
+
+        rotation_deg = resolve_scalar_or_range(cfg.rotation_deg, rng)
+        scale_factor = resolve_scalar_or_range(cfg.scale_factor, rng)
+        x_offset = resolve_scalar_or_range(cfg.x_offset, rng)
+        y_offset = resolve_scalar_or_range(cfg.y_offset, rng)
+
+        x1, y1, x2, y2 = target_box
+        box_w, box_h = (x2 - x1), (y2 - y1)
+        margin_x, margin_y = box_w * cfg.margin, box_h * cfg.margin
+        inner_x1, inner_y1 = x1 + margin_x, y1 + margin_y
+        inner_w = max(box_w - 2 * margin_x, 1.0)
+        inner_h = max(box_h - 2 * margin_y, 1.0)
+
+        rotated = rotate_and_scale_rgba(signature_rgba, rotation_deg, 1.0)
+        sig_h, sig_w = rotated.shape[:2]
+
+        fit_scale = min(inner_w / max(sig_w, 1), inner_h / max(sig_h, 1))
+        final_scale = max(fit_scale * scale_factor, 1e-3)
+
+        # Never let the signature shrink below a legible minimum height, even
+        # inside a very short box (real "sign here" lines are often only
+        # 12-20px tall at document resolution) -- a genuinely tiny box should
+        # make the signature overflow it, not vanish into sub-pixel noise.
+        min_height_scale = MIN_SIGNATURE_HEIGHT_PX / max(sig_h, 1)
+        final_scale = max(final_scale, min_height_scale)
+
+        placed = cv2.resize(
+            rotated, (max(int(round(sig_w * final_scale)), 1), max(int(round(sig_h * final_scale)), 1)),
+            interpolation=cv2.INTER_AREA if final_scale < 1.0 else cv2.INTER_CUBIC,
+        )
+        placed_h, placed_w = placed.shape[:2]
+
+        ax, ay = _anchor_top_left(cfg.anchor_point, inner_w, inner_h, placed_w, placed_h)
+        base_x = inner_x1 + ax + x_offset
+        base_y = inner_y1 + ay + y_offset
+
+        misplaced = bool(rng.uniform(0.0, 1.0) < cfg.misplacement_probability)
+        misplacement_dx = misplacement_dy = 0.0
+        if misplaced:
+            strength = resolve_scalar_or_range(cfg.misplacement_strength, rng)
+            max_shift = strength * max(box_w, box_h)
+            angle = rng.uniform(0, 2 * np.pi)
+            radius = rng.uniform(0.3, 1.0) * max_shift
+            misplacement_dx = float(np.cos(angle) * radius)
+            misplacement_dy = float(np.sin(angle) * radius)
+
+        final_x = base_x + misplacement_dx
+        final_y = base_y + misplacement_dy
+
+        if not cfg.allow_partial_outside and not misplaced:
+            final_x = float(np.clip(final_x, inner_x1, inner_x1 + max(inner_w - placed_w, 0)))
+            final_y = float(np.clip(final_y, inner_y1, inner_y1 + max(inner_h - placed_h, 0)))
+
+        # Hard safety clamp: never let the signature drift entirely off the physical page.
+        final_x = float(np.clip(final_x, -placed_w * 0.6, canvas_w - placed_w * 0.4))
+        final_y = float(np.clip(final_y, -placed_h * 0.6, canvas_h - placed_h * 0.4))
+
+        layer = np.zeros((canvas_h, canvas_w, 4), dtype=np.uint8)
+        self._paste(layer, placed, int(round(final_x)), int(round(final_y)))
+
+        intended_bbox: Box = (final_x, final_y, final_x + placed_w, final_y + placed_h)
+
+        return PlacementResult(
+            layer=layer,
+            target_box=target_box,
+            intended_bbox=intended_bbox,
+            x_offset=x_offset,
+            y_offset=y_offset,
+            rotation_deg=rotation_deg,
+            scale_factor=scale_factor,
+            anchor_point=cfg.anchor_point,
+            misplaced=misplaced,
+            misplacement_dx=misplacement_dx,
+            misplacement_dy=misplacement_dy,
+        )
+
+    @staticmethod
+    def _paste(canvas: np.ndarray, sprite: np.ndarray, x: int, y: int) -> None:
+        """Alpha-aware paste of ``sprite`` onto ``canvas`` at ``(x, y)``, clipped to bounds."""
+        canvas_h, canvas_w = canvas.shape[:2]
+        sprite_h, sprite_w = sprite.shape[:2]
+
+        dst_x1, dst_y1 = max(x, 0), max(y, 0)
+        dst_x2, dst_y2 = min(x + sprite_w, canvas_w), min(y + sprite_h, canvas_h)
+        if dst_x2 <= dst_x1 or dst_y2 <= dst_y1:
+            logger.warning("Placed signature falls entirely outside the canvas; skipping paste.")
+            return
+
+        src_x1, src_y1 = dst_x1 - x, dst_y1 - y
+        src_x2, src_y2 = src_x1 + (dst_x2 - dst_x1), src_y1 + (dst_y2 - dst_y1)
+
+        canvas[dst_y1:dst_y2, dst_x1:dst_x2] = sprite[src_y1:src_y2, src_x1:src_x2]

src/rendering/__init__.py

@@ -0,0 +1 @@
+"""Signature preprocessing and document/signature compositing."""

src/rendering/printed_text.py

@@ -0,0 +1,64 @@
+"""Renders a plain typed/printed name as an RGBA stamp (case_type "2b": no handwriting).
+
+Produces a tightly-cropped RGBA image shaped exactly like a
+:class:`~src.rendering.signature_preprocessor.SignaturePreprocessor` output,
+so it can flow through the existing
+:class:`~src.placement.placement_engine.PlacementEngine` and
+:class:`~src.rendering.renderer.Renderer` unchanged.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from PIL import Image, ImageDraw, ImageFont
+
+from src.utils.logging_utils import get_logger
+
+logger = get_logger(__name__)
+
+_FONT_CANDIDATES: tuple[str, ...] = (
+    "C:/Windows/Fonts/arial.ttf",
+    "C:/Windows/Fonts/calibri.ttf",
+    "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
+    "/usr/share/fonts/truetype/liberation/LiberationSans-Regular.ttf",
+    "/System/Library/Fonts/Helvetica.ttc",
+)
+
+_FONT_SIZE_PX = 64
+_PAD_PX = 6
+
+
+def _load_font(size: int = _FONT_SIZE_PX) -> "ImageFont.ImageFont":
+    for path in _FONT_CANDIDATES:
+        try:
+            return ImageFont.truetype(path, size)
+        except OSError:
+            continue
+    logger.warning("No truetype font found; falling back to PIL's bitmap default font.")
+    return ImageFont.load_default()
+
+
+def render_printed_name_stamp(name: str, ink_color: tuple[int, int, int] = (15, 15, 20)) -> np.ndarray:
+    """Render ``name`` as plain typed text, returned as a tightly-cropped RGBA stamp.
+
+    Args:
+        name: The printed/typed name to render (no handwriting stroke texture).
+        ink_color: Flat RGB color for the text (matches the pipeline's ink color pool).
+
+    Returns:
+        An ``(H, W, 4)`` uint8 RGBA array: opaque text on a transparent background.
+    """
+    font = _load_font()
+
+    scratch = Image.new("RGBA", (8, 8), (0, 0, 0, 0))
+    scratch_draw = ImageDraw.Draw(scratch)
+    text_bbox = scratch_draw.textbbox((0, 0), name, font=font)
+    text_w = max(text_bbox[2] - text_bbox[0], 1)
+    text_h = max(text_bbox[3] - text_bbox[1], 1)
+
+    canvas_w, canvas_h = text_w + 2 * _PAD_PX, text_h + 2 * _PAD_PX
+    image = Image.new("RGBA", (canvas_w, canvas_h), (0, 0, 0, 0))
+    draw = ImageDraw.Draw(image)
+    draw.text((_PAD_PX - text_bbox[0], _PAD_PX - text_bbox[1]), name, font=font, fill=(*ink_color, 255))
+
+    return np.array(image, dtype=np.uint8)

src/rendering/renderer.py

@@ -0,0 +1,105 @@
+"""Composites the placed (and signature-augmented) RGBA signature layer onto the document.
+
+Implements the blend modes and realism passes required by the spec: multiply
+blend, darken blend, alpha blend, configurable ink opacity, feathering
+(alpha-edge softening), a slight blur to match scan resolution, sensor/scan
+noise, and anti-aliasing.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import cv2
+import numpy as np
+
+from src.config.schema import RenderingConfig
+from src.utils.logging_utils import get_logger
+from src.utils.random_utils import SeedManager, resolve_scalar_or_range
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class RenderResult:
+    """The blended document image plus the resolved rendering parameters."""
+
+    image: np.ndarray
+    blend_mode: str
+    ink_opacity: float
+    blur_sigma: float
+    feather_px: float
+    scanner_noise: float
+
+
+class Renderer:
+    """Blends a signature RGBA layer onto a document canvas with configurable realism.
+
+    Example:
+        >>> renderer = Renderer(cfg.rendering)
+        >>> result = renderer.blend(document_rgb, signature_layer_rgba, seed_manager)
+    """
+
+    def __init__(self, config: RenderingConfig) -> None:
+        self.config = config
+
+    def blend(
+        self, document_rgb: np.ndarray, signature_layer_rgba: np.ndarray, seed_manager: SeedManager,
+    ) -> RenderResult:
+        """Blend the signature layer onto the document and return the composited image.
+
+        Args:
+            document_rgb: The scanned document canvas, ``(H, W, 3)`` uint8.
+            signature_layer_rgba: A full-canvas-sized RGBA layer (as produced
+                by :class:`~src.placement.placement_engine.PlacementEngine`,
+                after any signature-level augmentation), transparent outside
+                the signature.
+            seed_manager: Per-sample deterministic RNG provider.
+
+        Returns:
+            A :class:`RenderResult` with the composited uint8 RGB image and
+            the resolved rendering parameters (for metadata export).
+        """
+        cfg = self.config
+        rng = seed_manager.numpy_rng("rendering")
+
+        ink_opacity = resolve_scalar_or_range(cfg.ink_opacity, rng)
+        blur_sigma = resolve_scalar_or_range(cfg.blur_sigma, rng)
+        feather_px = resolve_scalar_or_range(cfg.feather_px, rng)
+        scanner_noise = resolve_scalar_or_range(cfg.scanner_noise, rng)
+
+        layer = signature_layer_rgba.astype(np.float32)
+        if feather_px > 0:
+            layer[:, :, 3] = cv2.GaussianBlur(layer[:, :, 3], (0, 0), sigmaX=feather_px)
+        if blur_sigma > 0:
+            layer = cv2.GaussianBlur(layer, (0, 0), sigmaX=blur_sigma)
+
+        sig_rgb = layer[:, :, :3]
+        alpha = np.clip(layer[:, :, 3] / 255.0, 0.0, 1.0) * float(np.clip(ink_opacity, 0.0, 1.0))
+        alpha3 = alpha[:, :, None]
+
+        base = document_rgb.astype(np.float32)
+
+        if cfg.blend_mode == "multiply":
+            blended_pixel = base * (sig_rgb / 255.0)
+        elif cfg.blend_mode == "darken":
+            blended_pixel = np.minimum(base, sig_rgb)
+        else:  # alpha
+            blended_pixel = sig_rgb
+
+        composited = base * (1 - alpha3) + blended_pixel * alpha3
+
+        if scanner_noise > 0:
+            noise = rng.normal(0.0, scanner_noise * 255.0, size=composited.shape).astype(np.float32)
+            composited += noise
+
+        if cfg.anti_alias:
+            composited = cv2.GaussianBlur(composited, (0, 0), sigmaX=0.3)
+
+        out = np.clip(composited, 0, 255).astype(np.uint8)
+
+        return RenderResult(
+            image=out, blend_mode=cfg.blend_mode, ink_opacity=round(ink_opacity, 4),
+            blur_sigma=round(blur_sigma, 4), feather_px=round(feather_px, 4),
+            scanner_noise=round(scanner_noise, 4),
+        )

src/rendering/signature_preprocessor.py

@@ -0,0 +1,123 @@
+"""Signature cleaning: white-background removal and alpha-mask extraction.
+
+Public handwritten signature datasets are typically flat scans: dark ink
+strokes on an off-white/paper background, with no alpha channel. This module
+converts such a scan into a clean RGBA "stamp" -- background fully
+transparent, ink strokes opaque-to-translucent according to how dark the
+original pixel was (preserving natural stroke texture: thin/faint pen
+lift-offs stay translucent, heavy strokes stay opaque) -- ready to be
+transformed and composited onto a document by :class:`~src.placement.placement_engine.PlacementEngine`
+and :class:`~src.rendering.renderer.Renderer`.
+"""
+
+from __future__ import annotations
+
+import cv2
+import numpy as np
+
+from src.utils.logging_utils import get_logger
+
+logger = get_logger(__name__)
+
+DEFAULT_INK_COLOR: tuple[int, int, int] = (18, 18, 24)
+
+
+class SignaturePreprocessor:
+    """Cleans a raw signature scan into a tightly-cropped, transparent RGBA stamp.
+
+    Example:
+        >>> pre = SignaturePreprocessor()
+        >>> rgba = pre.process(raw_signature_array)
+    """
+
+    def __init__(
+        self,
+        ink_color: tuple[int, int, int] = DEFAULT_INK_COLOR,
+        min_component_area: int = 4,
+        pad_px: int = 6,
+        alpha_gamma: float = 0.85,
+    ) -> None:
+        self.ink_color = ink_color
+        self.min_component_area = min_component_area
+        self.pad_px = pad_px
+        self.alpha_gamma = alpha_gamma
+
+    def process(self, raw_image: np.ndarray, ink_color: "tuple[int, int, int] | None" = None) -> np.ndarray:
+        """Convert a raw signature scan into a clean, tightly-cropped RGBA stamp.
+
+        Args:
+            raw_image: The raw signature image as loaded (grayscale ``(H, W)``,
+                RGB ``(H, W, 3)``, or RGBA ``(H, W, 4)`` uint8).
+            ink_color: Optional override for the flat ink color used for the
+                RGB channels (alpha still carries the natural stroke texture).
+
+        Returns:
+            An ``(H', W', 4)`` uint8 RGBA array, cropped tightly to the ink
+            content with a small transparent pad.
+        """
+        gray, existing_alpha = self._to_gray(raw_image)
+        gray = cv2.medianBlur(gray, 3)
+        alpha = self._compute_alpha(gray)
+        if existing_alpha is not None:
+            alpha = np.minimum(alpha, existing_alpha)
+        alpha = self._remove_speckles(alpha)
+        rgba = self._compose_rgba(alpha, ink_color or self.ink_color)
+        rgba = self._crop_to_content(rgba, pad=self.pad_px)
+        return rgba
+
+    @staticmethod
+    def _to_gray(raw_image: np.ndarray) -> tuple[np.ndarray, "np.ndarray | None"]:
+        if raw_image.ndim == 2:
+            return raw_image.copy(), None
+        if raw_image.shape[2] == 4:
+            rgb = raw_image[:, :, :3]
+            alpha = raw_image[:, :, 3]
+            gray = cv2.cvtColor(rgb, cv2.COLOR_RGB2GRAY)
+            return gray, alpha
+        gray = cv2.cvtColor(raw_image[:, :, :3], cv2.COLOR_RGB2GRAY)
+        return gray, None
+
+    @staticmethod
+    def _compute_alpha(gray: np.ndarray) -> np.ndarray:
+        gray_f = gray.astype(np.float64)
+        background = float(np.percentile(gray_f, 92))
+        dark_pixels = gray_f[gray_f < background - 8]
+        dark_level = float(np.percentile(dark_pixels, 5)) if dark_pixels.size > 20 else max(background - 140, 0.0)
+        denom = max(background - dark_level, 1e-3)
+
+        raw = (background - gray_f) / denom
+        raw = np.clip(raw, 0.0, 1.0)
+        # Discard near-background noise (sub-threshold jitter from scanning artifacts).
+        raw[raw < 0.06] = 0.0
+        softened = raw**0.85
+        return (softened * 255.0).astype(np.uint8)
+
+    def _remove_speckles(self, alpha: np.ndarray) -> np.ndarray:
+        binary = (alpha > 15).astype(np.uint8)
+        n_labels, labels, stats, _ = cv2.connectedComponentsWithStats(binary, connectivity=8)
+        if n_labels <= 1:
+            return alpha
+        cleaned = alpha.copy()
+        for label in range(1, n_labels):
+            area = stats[label, cv2.CC_STAT_AREA]
+            if area < self.min_component_area:
+                cleaned[labels == label] = 0
+        return cleaned
+
+    @staticmethod
+    def _compose_rgba(alpha: np.ndarray, ink_color: tuple[int, int, int]) -> np.ndarray:
+        h, w = alpha.shape
+        rgb = np.empty((h, w, 3), dtype=np.uint8)
+        rgb[:, :] = ink_color
+        return np.dstack([rgb, alpha])
+
+    @staticmethod
+    def _crop_to_content(rgba: np.ndarray, pad: int) -> np.ndarray:
+        alpha = rgba[:, :, 3]
+        ys, xs = np.where(alpha > 4)
+        if ys.size == 0:
+            logger.warning("Signature preprocessing found no ink pixels; returning a 1x1 transparent stamp.")
+            return np.zeros((1, 1, 4), dtype=np.uint8)
+        y1, y2 = max(ys.min() - pad, 0), min(ys.max() + pad + 1, rgba.shape[0])
+        x1, x2 = max(xs.min() - pad, 0), min(xs.max() + pad + 1, rgba.shape[1])
+        return rgba[y1:y2, x1:x2].copy()

src/signatures/__init__.py

@@ -0,0 +1 @@
+"""Signature dataset discovery and sampling."""

src/signatures/signature_dataset.py

@@ -0,0 +1,208 @@
+"""Recursive discovery of the public handwritten signature dataset.
+
+Scans ``dataset/`` recursively for signature images (PNG/JPG/JPEG/TIFF/BMP),
+building an internal database without requiring any particular naming
+convention or folder layout. Two conventions are detected automatically
+when present, but neither is required:
+
+* ``dataset/metadata.csv`` -- if present, associates files with a signer
+  identity via a ``filename``/``path`` column plus a ``signer``/``name``
+  column, and optionally a ``source_type`` and ``script`` column (the
+  handwriting script the signature is written in, e.g. ``hindi``,
+  ``bengali``, ``latin`` -- see ``dataset/hindi_bengali/`` for the bundled
+  multi-script signer pool).
+* Filenames matching CEDAR-style ``original_<signer>_<sample>.png`` /
+  ``forgeries_<signer>_<sample>.png`` (as found in the bundled dataset) --
+  used to recover a signer group id and genuine/forged label even without
+  a metadata file.
+
+Otherwise, each signature is assigned an automatically generated id and its
+immediate parent folder name is used as its signer group (matching the
+``dataset/personNNN/*.png`` layout described in the project spec).
+"""
+
+from __future__ import annotations
+
+import csv
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+
+from src.utils.image_io import discover_images
+from src.utils.logging_utils import get_logger
+
+logger = get_logger(__name__)
+
+_CEDAR_PATTERN = re.compile(r"^(?P<prefix>[a-zA-Z]+)_(?P<signer>\d+)_(?P<sample>\d+)$")
+
+
+@dataclass(frozen=True)
+class SignatureRecord:
+    """One discovered signature image and its inferred identity metadata."""
+
+    signature_id: str
+    path: Path
+    signer_group: str
+    source_type: str  # "genuine" | "forged" | "unknown"
+    script: str = "latin"  # handwriting script, e.g. "latin" | "hindi" | "bengali"
+
+
+class SignatureDataset:
+    """Discovers and indexes the signature image dataset for deterministic sampling.
+
+    Example:
+        >>> ds = SignatureDataset("dataset")
+        >>> ds.discover()
+        >>> record = ds.sample(rng, source_filter="genuine")
+    """
+
+    def __init__(self, dataset_dir: "str | Path") -> None:
+        self.dataset_dir = Path(dataset_dir)
+        self._records: "list[SignatureRecord] | None" = None
+        self._by_id: "dict[str, SignatureRecord] | None" = None
+
+    def discover(self) -> list[SignatureRecord]:
+        """Recursively discover all signature images and build the internal database."""
+        if self._records is not None:
+            return self._records
+
+        paths = discover_images(self.dataset_dir)
+        if not paths:
+            raise FileNotFoundError(f"No signature images found under '{self.dataset_dir}'.")
+
+        metadata_map = self._load_metadata_csv()
+
+        records: list[SignatureRecord] = []
+        for idx, path in enumerate(paths):
+            rel = path.relative_to(self.dataset_dir)
+            stem = path.stem
+
+            meta = metadata_map.get(rel.as_posix()) or metadata_map.get(path.name)
+            signer_group = None
+            source_type = "unknown"
+
+            match = _CEDAR_PATTERN.match(stem)
+            if match:
+                signer_group = f"signer_{int(match.group('signer')):04d}"
+                prefix = match.group("prefix").lower()
+                if "orig" in prefix or "genuine" in prefix:
+                    source_type = "genuine"
+                elif "forg" in prefix:
+                    source_type = "forged"
+
+            if meta and meta.get("signer"):
+                signer_group = meta["signer"]
+            if meta and meta.get("source_type"):
+                source_type = meta["source_type"]
+
+            if signer_group is None:
+                signer_group = rel.parent.as_posix() if rel.parent != Path(".") else "unassigned"
+
+            if source_type == "unknown":
+                lowered = rel.as_posix().lower()
+                if "genuine" in lowered or "original" in lowered:
+                    source_type = "genuine"
+                elif "forg" in lowered:
+                    source_type = "forged"
+
+            signature_id = meta.get("signature_id") if meta else None
+            if not signature_id:
+                signature_id = f"sig_{idx:06d}"
+
+            script = (meta.get("script") if meta else None) or "latin"
+
+            records.append(SignatureRecord(signature_id, path, signer_group, source_type, script))
+
+        self._records = records
+        self._by_id = {r.signature_id: r for r in records}
+        n_genuine = sum(1 for r in records if r.source_type == "genuine")
+        n_forged = sum(1 for r in records if r.source_type == "forged")
+        n_groups = len({r.signer_group for r in records})
+        logger.info(
+            "Discovered %d signature images (%d genuine, %d forged, %d unknown) across %d signer group(s).",
+            len(records), n_genuine, n_forged, len(records) - n_genuine - n_forged, n_groups,
+        )
+        return records
+
+    def _load_metadata_csv(self) -> dict:
+        csv_path = self.dataset_dir / "metadata.csv"
+        if not csv_path.exists():
+            return {}
+        mapping: dict = {}
+        with csv_path.open("r", encoding="utf-8", newline="") as f:
+            reader = csv.DictReader(f)
+            for row in reader:
+                key = row.get("path") or row.get("filename") or row.get("file")
+                if not key:
+                    continue
+                normalized = {k.strip().lower(): (v.strip() if v else v) for k, v in row.items()}
+                signer = normalized.get("signer") or normalized.get("name") or normalized.get("signer_name")
+                mapping[key] = {
+                    "signer": signer,
+                    "source_type": normalized.get("source_type") or normalized.get("type"),
+                    "signature_id": normalized.get("signature_id") or normalized.get("id"),
+                    "script": normalized.get("script"),
+                }
+        if mapping:
+            logger.info("Loaded signature metadata for %d entries from %s", len(mapping), csv_path)
+        return mapping
+
+    def get(self, signature_id: str) -> SignatureRecord:
+        """Return a signature record by id."""
+        self.discover()
+        if signature_id not in self._by_id:
+            raise KeyError(f"Unknown signature id '{signature_id}'.")
+        return self._by_id[signature_id]
+
+    def filtered_records(self, source_filter: str = "any") -> list[SignatureRecord]:
+        """Return records matching ``source_filter`` ("genuine" | "forged" | "any")."""
+        records = self.discover()
+        if source_filter == "any":
+            return records
+        filtered = [r for r in records if r.source_type == source_filter]
+        if not filtered:
+            logger.warning(
+                "No signatures match source_filter='%s'; falling back to the full dataset.",
+                source_filter,
+            )
+            return records
+        return filtered
+
+    def sample(self, rng: np.random.Generator, source_filter: str = "genuine") -> SignatureRecord:
+        """Deterministically sample one signature record using the given seeded generator."""
+        pool = self.filtered_records(source_filter)
+        idx = int(rng.integers(0, len(pool)))
+        return pool[idx]
+
+    def signer_groups(self) -> list[str]:
+        """Return every distinct signer group id, sorted for deterministic indexing."""
+        return sorted({r.signer_group for r in self.discover()})
+
+    def records_for_group(self, signer_group: str, source_filter: str = "any") -> list[SignatureRecord]:
+        """Return records belonging to one signer group, optionally filtered by source type."""
+        records = [r for r in self.discover() if r.signer_group == signer_group]
+        if source_filter == "any":
+            return records
+        filtered = [r for r in records if r.source_type == source_filter]
+        if not filtered:
+            logger.warning(
+                "Signer group '%s' has no '%s' records; falling back to all its records.",
+                signer_group, source_filter,
+            )
+            return records
+        return filtered
+
+    def sample_from_group(
+        self, rng: np.random.Generator, signer_group: str, source_filter: str = "genuine",
+    ) -> SignatureRecord:
+        """Deterministically sample one signature record from a specific signer group."""
+        pool = self.records_for_group(signer_group, source_filter)
+        idx = int(rng.integers(0, len(pool)))
+        return pool[idx]
+
+    def script_for_group(self, signer_group: str) -> str:
+        """Return the handwriting script associated with a signer group (all its records share one)."""
+        records = self.records_for_group(signer_group, source_filter="any")
+        return records[0].script if records else "latin"

src/templates/__init__.py

@@ -0,0 +1 @@
+"""Template discovery, annotation loading, and CV-based signature box detection."""

src/templates/annotation_schema.py

@@ -0,0 +1,69 @@
+"""Pydantic schema for template annotation files (``annotations/<template_id>.json``)."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class SignatureBoxAnnotation(BaseModel):
+    """A single signature field on a page, in pixel coordinates of the template image."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    id: str
+    x1: float
+    y1: float
+    x2: float
+    y2: float
+    role: str = "Signer"
+    name: str = "Signer"
+
+    @model_validator(mode="after")
+    def _normalize_box(self) -> "SignatureBoxAnnotation":
+        x1, x2 = sorted((self.x1, self.x2))
+        y1, y2 = sorted((self.y1, self.y2))
+        self.x1, self.x2, self.y1, self.y2 = x1, x2, y1, y2
+        if x2 <= x1 or y2 <= y1:
+            raise ValueError(f"Signature box '{self.id}' has non-positive area: {self.as_tuple()}")
+        return self
+
+    def as_tuple(self) -> tuple[float, float, float, float]:
+        """Return the box as ``(x1, y1, x2, y2)``."""
+        return (self.x1, self.y1, self.x2, self.y2)
+
+    @property
+    def width(self) -> float:
+        return self.x2 - self.x1
+
+    @property
+    def height(self) -> float:
+        return self.y2 - self.y1
+
+
+class TemplatePageAnnotation(BaseModel):
+    """A single page of a template document."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    page: int = 1
+    page_size: tuple[int, int]
+    dpi: int = 300
+    signature_boxes: list[SignatureBoxAnnotation] = Field(default_factory=list)
+
+
+class TemplateAnnotation(BaseModel):
+    """Full annotation for one template document (possibly multi-page)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    id: str
+    source_image: "str | None" = None
+    document_type: "str | None" = None
+    pages: list[TemplatePageAnnotation]
+    auto_detected: bool = False
+
+    def page_by_number(self, page: int) -> TemplatePageAnnotation:
+        for p in self.pages:
+            if p.page == page:
+                return p
+        raise KeyError(f"Template '{self.id}' has no page {page}")

src/templates/box_detector.py

@@ -0,0 +1,133 @@
+"""Mode 1: automatic signature-field detection via classical computer vision.
+
+Bank document signature fields are almost always denoted by a horizontal
+"sign here" rule (an underscore/line) with a caption below it ("Signature",
+"Authorized Signatory", ...). This detector isolates long, thin horizontal
+line segments via morphological opening, filters them by geometry, and
+places a signature box directly above each surviving line -- the same
+region a human would use to place a pen.
+
+This is a heuristic, not a learned layout model; it is intentionally used
+only as a *fallback* when no manual annotation file exists (Mode 2 is
+preferred whenever available, see :class:`~src.templates.template_loader.TemplateLoader`).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import cv2
+import numpy as np
+
+from src.utils.logging_utils import get_logger
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class DetectedLine:
+    x: int
+    y: int
+    w: int
+    h: int
+
+    @property
+    def aspect_ratio(self) -> float:
+        return self.w / max(self.h, 1)
+
+
+def _binarize(gray: np.ndarray) -> np.ndarray:
+    """Return a binary ink mask (255 = ink) using adaptive thresholding."""
+    blurred = cv2.GaussianBlur(gray, (3, 3), 0)
+    binary = cv2.adaptiveThreshold(
+        blurred, 255, cv2.ADAPTIVE_THRESH_GAUSSIAN_C, cv2.THRESH_BINARY_INV, 25, 10,
+    )
+    return binary
+
+
+def _detect_horizontal_lines(binary: np.ndarray, min_width_frac: float = 0.08) -> list[DetectedLine]:
+    """Detect long horizontal rule segments (signature/blank-field underscores)."""
+    h, w = binary.shape[:2]
+    kernel_w = max(int(w * min_width_frac), 15)
+    horiz_kernel = cv2.getStructuringElement(cv2.MORPH_RECT, (kernel_w, 1))
+    opened = cv2.morphologyEx(binary, cv2.MORPH_OPEN, horiz_kernel, iterations=1)
+    opened = cv2.dilate(opened, cv2.getStructuringElement(cv2.MORPH_RECT, (3, 1)), iterations=1)
+
+    contours, _ = cv2.findContours(opened, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+    lines: list[DetectedLine] = []
+    for c in contours:
+        x, y, cw, ch = cv2.boundingRect(c)
+        line = DetectedLine(x, y, cw, ch)
+        if line.w < w * min_width_frac:
+            continue
+        if line.aspect_ratio < 6.0:
+            continue
+        if line.h > 12:
+            continue
+        lines.append(line)
+    return lines
+
+
+def _merge_nearby_lines(lines: list[DetectedLine], y_tol: int = 8) -> list[DetectedLine]:
+    """Merge line fragments that are on the same visual row into one segment."""
+    if not lines:
+        return []
+    lines = sorted(lines, key=lambda l: (l.y, l.x))
+    merged: list[DetectedLine] = [lines[0]]
+    for line in lines[1:]:
+        last = merged[-1]
+        if abs(line.y - last.y) <= y_tol and line.x <= last.x + last.w + 40:
+            new_x2 = max(last.x + last.w, line.x + line.w)
+            merged[-1] = DetectedLine(last.x, min(last.y, line.y), new_x2 - last.x, max(last.h, line.h))
+        else:
+            merged.append(line)
+    return merged
+
+
+def detect_signature_boxes(
+    image_rgb: np.ndarray,
+    max_boxes: int = 4,
+    box_height_frac: float = 0.55,
+) -> list[tuple[float, float, float, float]]:
+    """Detect likely signature box regions above horizontal rule lines.
+
+    Args:
+        image_rgb: The template page as an ``(H, W, 3)`` uint8 array.
+        max_boxes: Maximum number of candidate boxes to return (keeps the
+            widest/most line-like candidates, which correlate with genuine
+            signature/date fields rather than table gridlines).
+        box_height_frac: Height of the returned box above the line, as a
+            fraction of the line's width (wider lines get proportionally
+            taller signature boxes, capped below).
+
+    Returns:
+        A list of ``(x1, y1, x2, y2)`` boxes in image pixel coordinates,
+        sorted left-to-right, top-to-bottom. Empty if nothing was detected.
+    """
+    h, w = image_rgb.shape[:2]
+    gray = cv2.cvtColor(image_rgb, cv2.COLOR_RGB2GRAY)
+    binary = _binarize(gray)
+    lines = _detect_horizontal_lines(binary)
+    lines = _merge_nearby_lines(lines)
+
+    if not lines:
+        logger.warning("Automatic signature box detection found no candidate lines.")
+        return []
+
+    lines = sorted(lines, key=lambda l: l.w, reverse=True)[: max_boxes * 2]
+
+    boxes: list[tuple[float, float, float, float]] = []
+    for line in lines:
+        box_h = min(max(int(line.w * box_height_frac * 0.25), 20), 80)
+        x1 = float(max(line.x, 0))
+        x2 = float(min(line.x + line.w, w))
+        y2 = float(line.y)
+        y1 = float(max(line.y - box_h, 0))
+        if (x2 - x1) < 20 or (y2 - y1) < 8:
+            continue
+        boxes.append((x1, y1, x2, y2))
+
+    boxes = boxes[:max_boxes]
+    boxes.sort(key=lambda b: (round(b[1] / 50.0), b[0]))
+    logger.info("Automatic detection found %d candidate signature box(es).", len(boxes))
+    return boxes

src/templates/template_loader.py

@@ -0,0 +1,146 @@
+"""Template discovery and annotation resolution.
+
+Scans ``image/`` recursively for scanned bank document templates, assigns
+each a stable ``template_id`` (``bank_doc_01``, ``bank_doc_02``, ...) based
+on a deterministic sort of their paths, and resolves signature-box
+annotations for each using, in order of preference:
+
+1. **Mode 2 (preferred when present):** a manually authored
+   ``annotations/<template_id>.json`` file.
+2. **Mode 1 (fallback):** automatic CV-based detection
+   (:mod:`src.templates.box_detector`), whose result is cached to
+   ``annotations/<template_id>.json`` so subsequent runs reuse it without
+   re-running detection.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+
+from src.templates.annotation_schema import TemplateAnnotation, TemplatePageAnnotation, SignatureBoxAnnotation
+from src.templates.box_detector import detect_signature_boxes
+from src.utils.image_io import discover_images, load_image_rgb
+from src.utils.logging_utils import get_logger
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class Template:
+    """A discovered template document: its image path and resolved annotation."""
+
+    template_id: str
+    image_path: Path
+    annotation: TemplateAnnotation
+
+
+class TemplateLoader:
+    """Discovers bank document templates and resolves their signature-box annotations.
+
+    Example:
+        >>> loader = TemplateLoader(image_dir="image", annotations_dir="annotations")
+        >>> templates = loader.discover()
+        >>> tmpl = loader.get("bank_doc_01")
+    """
+
+    def __init__(self, image_dir: "str | Path", annotations_dir: "str | Path") -> None:
+        self.image_dir = Path(image_dir)
+        self.annotations_dir = Path(annotations_dir)
+        self.annotations_dir.mkdir(parents=True, exist_ok=True)
+        self._templates: "dict[str, Template] | None" = None
+
+    def discover(self) -> "dict[str, Template]":
+        """Discover all templates under ``image_dir`` and resolve their annotations.
+
+        Returns:
+            An ordered mapping of ``template_id -> Template``, sorted by id.
+        """
+        if self._templates is not None:
+            return self._templates
+
+        image_paths = discover_images(self.image_dir)
+        if not image_paths:
+            raise FileNotFoundError(
+                f"No supported template images found under '{self.image_dir}'. "
+                "Expected PNG/JPG/JPEG/TIFF/BMP files."
+            )
+
+        templates: "dict[str, Template]" = {}
+        for idx, image_path in enumerate(image_paths, start=1):
+            template_id = f"bank_doc_{idx:02d}"
+            annotation = self._resolve_annotation(template_id, image_path)
+            templates[template_id] = Template(template_id, image_path, annotation)
+            logger.info(
+                "Registered template '%s' -> %s (%d signature box(es), auto_detected=%s)",
+                template_id, image_path, sum(len(p.signature_boxes) for p in annotation.pages),
+                annotation.auto_detected,
+            )
+
+        self._templates = templates
+        return templates
+
+    def get(self, template_id: str) -> Template:
+        """Return a discovered template by id, raising ``KeyError`` if unknown."""
+        templates = self.discover()
+        if template_id not in templates:
+            raise KeyError(f"Unknown template id '{template_id}'. Known: {sorted(templates)}")
+        return templates[template_id]
+
+    def list_ids(self) -> list[str]:
+        """Return all discovered template ids, sorted."""
+        return sorted(self.discover().keys())
+
+    def random_template(self, rng: np.random.Generator) -> Template:
+        """Pick a uniformly random template using the given seeded generator."""
+        ids = self.list_ids()
+        choice = ids[int(rng.integers(0, len(ids)))]
+        return self.get(choice)
+
+    def _resolve_annotation(self, template_id: str, image_path: Path) -> TemplateAnnotation:
+        annotation_path = self.annotations_dir / f"{template_id}.json"
+        if annotation_path.exists():
+            data = json.loads(annotation_path.read_text(encoding="utf-8"))
+            return TemplateAnnotation.model_validate(data)
+
+        logger.warning(
+            "No manual annotation found for '%s'; falling back to automatic CV detection.",
+            template_id,
+        )
+        annotation = self._auto_detect_annotation(template_id, image_path)
+        annotation_path.write_text(
+            json.dumps(annotation.model_dump(), indent=2), encoding="utf-8"
+        )
+        logger.info("Cached auto-detected annotation to %s", annotation_path)
+        return annotation
+
+    def _auto_detect_annotation(self, template_id: str, image_path: Path) -> TemplateAnnotation:
+        image = load_image_rgb(image_path)
+        h, w = image.shape[:2]
+        boxes = detect_signature_boxes(image)
+
+        if not boxes:
+            # Last-resort fallback: a generic box in the lower-right quadrant,
+            # where signature fields conventionally sit on Western bank forms.
+            boxes = [(w * 0.55, h * 0.80, w * 0.92, h * 0.90)]
+            logger.warning(
+                "'%s': no lines detected; using generic lower-right fallback box.", template_id
+            )
+
+        signature_boxes = [
+            SignatureBoxAnnotation(
+                id=f"sig{i + 1}", x1=x1, y1=y1, x2=x2, y2=y2, role="Signer", name="Signer",
+            )
+            for i, (x1, y1, x2, y2) in enumerate(boxes)
+        ]
+        page = TemplatePageAnnotation(page=1, page_size=(w, h), dpi=300, signature_boxes=signature_boxes)
+        return TemplateAnnotation(
+            id=template_id,
+            source_image=str(image_path.as_posix()),
+            document_type="unknown",
+            pages=[page],
+            auto_detected=True,
+        )

src/utils/__init__.py

@@ -0,0 +1 @@
+"""Shared utilities: logging, deterministic RNG management, geometry helpers, I/O, name generation."""

src/utils/geometry_utils.py

@@ -0,0 +1,158 @@
+"""Geometry helper functions built on Shapely and NumPy.
+
+Centralizes every polygon/box computation used by placement and analysis so
+that the same, well-tested math backs both "where should the signature go"
+and "how well did it land" — avoiding subtle mismatches between the two.
+"""
+
+from __future__ import annotations
+
+from typing import Sequence
+
+import numpy as np
+from shapely.geometry import Polygon, box as shapely_box
+from shapely.validation import make_valid
+
+Box = tuple[float, float, float, float]  # x1, y1, x2, y2
+
+
+def box_to_polygon(box_coords: Box) -> Polygon:
+    """Convert an ``(x1, y1, x2, y2)`` axis-aligned box into a Shapely polygon."""
+    x1, y1, x2, y2 = box_coords
+    return shapely_box(min(x1, x2), min(y1, y2), max(x1, x2), max(y1, y2))
+
+
+def points_to_polygon(points: Sequence[Sequence[float]]) -> Polygon:
+    """Build a valid Shapely polygon from an ordered list of ``(x, y)`` points.
+
+    Degenerate inputs (fewer than 3 points, zero area) are expanded into a
+    minimal valid polygon by buffering, so downstream geometry ops never
+    raise on edge cases like a single-pixel detected signature.
+    """
+    pts = np.asarray(points, dtype=float)
+    if len(pts) < 3:
+        if len(pts) == 0:
+            return Polygon()
+        center = pts.mean(axis=0)
+        return shapely_box(center[0] - 0.5, center[1] - 0.5, center[0] + 0.5, center[1] + 0.5)
+    poly = Polygon(pts)
+    if not poly.is_valid:
+        poly = make_valid(poly)
+        if poly.geom_type != "Polygon":
+            poly = poly.convex_hull
+    if poly.area <= 0:
+        poly = poly.buffer(0.5)
+    return poly
+
+
+def safe_area(poly: Polygon) -> float:
+    """Return polygon area, guarding against ``None``/empty geometries."""
+    if poly is None or poly.is_empty:
+        return 0.0
+    return float(poly.area)
+
+
+def intersection_area(poly_a: Polygon, poly_b: Polygon) -> float:
+    """Return the intersection area of two polygons, 0 if either is empty/invalid."""
+    if poly_a is None or poly_b is None or poly_a.is_empty or poly_b.is_empty:
+        return 0.0
+    if not poly_a.is_valid:
+        poly_a = make_valid(poly_a)
+    if not poly_b.is_valid:
+        poly_b = make_valid(poly_b)
+    try:
+        return float(poly_a.intersection(poly_b).area)
+    except Exception:
+        return 0.0
+
+
+def iou(poly_a: Polygon, poly_b: Polygon) -> float:
+    """Intersection-over-Union of two polygons."""
+    inter = intersection_area(poly_a, poly_b)
+    union = safe_area(poly_a) + safe_area(poly_b) - inter
+    if union <= 0:
+        return 0.0
+    return float(np.clip(inter / union, 0.0, 1.0))
+
+
+def coverage_pct(target_box_poly: Polygon, signature_poly: Polygon) -> float:
+    """``100 * intersection(target_box, polygon) / area(target_box)``."""
+    target_area = safe_area(target_box_poly)
+    if target_area <= 0:
+        return 0.0
+    inter = intersection_area(target_box_poly, signature_poly)
+    return float(np.clip(100.0 * inter / target_area, 0.0, 100.0))
+
+
+def containment_pct(target_box_poly: Polygon, signature_poly: Polygon) -> float:
+    """``100 * intersection(target_box, polygon) / area(polygon)``."""
+    sig_area = safe_area(signature_poly)
+    if sig_area <= 0:
+        return 0.0
+    inter = intersection_area(target_box_poly, signature_poly)
+    return float(np.clip(100.0 * inter / sig_area, 0.0, 100.0))
+
+
+def centroid_of(poly: Polygon) -> tuple[float, float]:
+    """Return the ``(x, y)`` centroid of a polygon, ``(nan, nan)`` if empty."""
+    if poly is None or poly.is_empty:
+        return (float("nan"), float("nan"))
+    c = poly.centroid
+    return (float(c.x), float(c.y))
+
+
+def box_center(box_coords: Box) -> tuple[float, float]:
+    """Return the center point of an axis-aligned box."""
+    x1, y1, x2, y2 = box_coords
+    return ((x1 + x2) / 2.0, (y1 + y2) / 2.0)
+
+
+def box_size(box_coords: Box) -> tuple[float, float]:
+    """Return ``(width, height)`` of an axis-aligned box."""
+    x1, y1, x2, y2 = box_coords
+    return (abs(x2 - x1), abs(y2 - y1))
+
+
+def distance_between(p1: tuple[float, float], p2: tuple[float, float]) -> float:
+    """Euclidean distance between two points, ``nan``-safe."""
+    if any(np.isnan(v) for v in (*p1, *p2)):
+        return float("nan")
+    return float(np.hypot(p1[0] - p2[0], p1[1] - p2[1]))
+
+
+def margin_utilization(box_coords: Box, signature_poly: Polygon) -> float:
+    """Fraction of the box's available margin consumed by the signature (0..1+).
+
+    0 means the signature sits exactly at the box center with no spatial
+    extent; 1 means it exactly fills the box's half-diagonal. Values above 1
+    indicate the signature protrudes outside the box.
+    """
+    if signature_poly is None or signature_poly.is_empty:
+        return 0.0
+    bx, by = box_center(box_coords)
+    bw, bh = box_size(box_coords)
+    half_diag = float(np.hypot(bw, bh) / 2.0) or 1e-6
+    minx, miny, maxx, maxy = signature_poly.bounds
+    corners = [(minx, miny), (minx, maxy), (maxx, miny), (maxx, maxy)]
+    max_dist = max(distance_between((bx, by), c) for c in corners)
+    return float(max_dist / half_diag)
+
+
+def clamp01(value: float) -> float:
+    """Clamp a float into ``[0, 1]``, mapping NaN to 0."""
+    if value is None or np.isnan(value):
+        return 0.0
+    return float(np.clip(value, 0.0, 1.0))
+
+
+def rotated_rect_polygon(center: tuple[float, float], size: tuple[float, float], angle_deg: float) -> Polygon:
+    """Build a Shapely polygon for a rectangle rotated about its center (OpenCV convention)."""
+    cx, cy = center
+    w, h = size
+    theta = np.deg2rad(angle_deg)
+    dx = w / 2.0
+    dy = h / 2.0
+    corners = np.array([(-dx, -dy), (dx, -dy), (dx, dy), (-dx, dy)])
+    rot = np.array([[np.cos(theta), -np.sin(theta)], [np.sin(theta), np.cos(theta)]])
+    rotated = corners @ rot.T + np.array([cx, cy])
+    return Polygon(rotated)

src/utils/image_io.py

@@ -0,0 +1,62 @@
+"""Image I/O helpers built on Pillow + NumPy.
+
+Pillow is used for decoding (broad format support: PNG/JPG/JPEG/TIFF/BMP)
+while all pixel manipulation downstream is done with NumPy/OpenCV arrays in
+RGB(A) uint8 layout for consistency across the pipeline.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+from PIL import Image
+
+SUPPORTED_IMAGE_EXTENSIONS: tuple[str, ...] = (
+    ".png", ".jpg", ".jpeg", ".tif", ".tiff", ".bmp",
+)
+
+
+def load_image_rgb(path: "Path | str") -> np.ndarray:
+    """Load an image file as an ``(H, W, 3)`` uint8 RGB array."""
+    with Image.open(path) as im:
+        return np.array(im.convert("RGB"))
+
+
+def load_image_any(path: "Path | str") -> np.ndarray:
+    """Load an image preserving its native mode (grayscale, RGB, or RGBA) as uint8.
+
+    Used for signature source images, which may be grayscale scans, palette
+    images, or already have an alpha channel.
+    """
+    with Image.open(path) as im:
+        if im.mode in ("L", "RGB", "RGBA"):
+            return np.array(im)
+        if im.mode == "LA":
+            return np.array(im.convert("RGBA"))
+        # Palette / CMYK / other -> normalize to RGB
+        return np.array(im.convert("RGB"))
+
+
+def save_image_rgb(path: "Path | str", array: np.ndarray) -> None:
+    """Save an ``(H, W, 3)`` or ``(H, W, 4)`` uint8 array as PNG/JPEG depending on extension."""
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    mode = "RGBA" if array.ndim == 3 and array.shape[2] == 4 else "RGB"
+    Image.fromarray(array.astype(np.uint8), mode=mode).save(path)
+
+
+def save_image_gray(path: "Path | str", array: np.ndarray) -> None:
+    """Save a single-channel uint8 array as a grayscale image."""
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    Image.fromarray(array.astype(np.uint8), mode="L").save(path)
+
+
+def discover_images(root: "Path | str", extensions: tuple[str, ...] = SUPPORTED_IMAGE_EXTENSIONS) -> list[Path]:
+    """Recursively discover image files under ``root``, sorted deterministically."""
+    root = Path(root)
+    if not root.exists():
+        return []
+    found = [p for p in root.rglob("*") if p.is_file() and p.suffix.lower() in extensions]
+    return sorted(found, key=lambda p: p.as_posix().lower())

src/utils/logging_utils.py

@@ -0,0 +1,53 @@
+"""Centralized logging configuration.
+
+The pipeline uses ``logging`` exclusively (no ``print``). Every module obtains
+its logger via :func:`get_logger`, which guarantees handlers are configured
+exactly once per process, even under multiprocessing worker re-imports.
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+from pathlib import Path
+
+_CONFIGURED = False
+
+LOG_FORMAT = "%(asctime)s | %(levelname)-8s | %(processName)s | %(name)s | %(message)s"
+DATE_FORMAT = "%Y-%m-%d %H:%M:%S"
+
+
+def configure_logging(level: int = logging.INFO, log_file: "Path | None" = None) -> None:
+    """Configure the root logger once for the entire process.
+
+    Args:
+        level: Root logging level (e.g. ``logging.INFO``, ``logging.DEBUG``).
+        log_file: Optional file path to additionally write logs to.
+    """
+    global _CONFIGURED
+    root = logging.getLogger()
+    if _CONFIGURED:
+        root.setLevel(level)
+        return
+
+    root.setLevel(level)
+    formatter = logging.Formatter(LOG_FORMAT, datefmt=DATE_FORMAT)
+
+    stream_handler = logging.StreamHandler(stream=sys.stdout)
+    stream_handler.setFormatter(formatter)
+    root.addHandler(stream_handler)
+
+    if log_file is not None:
+        log_file.parent.mkdir(parents=True, exist_ok=True)
+        file_handler = logging.FileHandler(log_file, encoding="utf-8")
+        file_handler.setFormatter(formatter)
+        root.addHandler(file_handler)
+
+    _CONFIGURED = True
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Return a module-scoped logger, configuring root logging with sane defaults if needed."""
+    if not _CONFIGURED:
+        configure_logging()
+    return logging.getLogger(name)

src/utils/names.py

@@ -0,0 +1,62 @@
+"""Deterministic synthetic signer name/role generation.
+
+No external dependency (e.g. Faker) is required: a compact, self-contained
+name pool keeps the pipeline dependency-light and fully reproducible from a
+seed alone (Faker's own generators are not guaranteed stable across
+versions, which would break the "same seed -> same output" contract).
+"""
+
+from __future__ import annotations
+
+import random
+
+FIRST_NAMES: tuple[str, ...] = (
+    "James", "Mary", "Robert", "Patricia", "John", "Jennifer", "Michael", "Linda",
+    "David", "Elizabeth", "William", "Barbara", "Richard", "Susan", "Joseph", "Jessica",
+    "Thomas", "Sarah", "Charles", "Karen", "Christopher", "Nancy", "Daniel", "Lisa",
+    "Matthew", "Betty", "Anthony", "Margaret", "Mark", "Sandra", "Donald", "Ashley",
+    "Steven", "Kimberly", "Paul", "Emily", "Andrew", "Donna", "Joshua", "Michelle",
+    "Kenneth", "Carol", "Kevin", "Amanda", "Brian", "Melissa", "George", "Deborah",
+    "Edward", "Stephanie", "Ronald", "Rebecca", "Timothy", "Laura", "Jason", "Sharon",
+    "Jeffrey", "Cynthia", "Ryan", "Kathleen", "Jacob", "Amy", "Gary", "Angela",
+    "Nicholas", "Shirley", "Eric", "Anna", "Jonathan", "Brenda", "Stephen", "Pamela",
+    "Larry", "Emma", "Justin", "Nicole", "Scott", "Helen", "Brandon", "Samantha",
+    "Wei", "Mei", "Hiroshi", "Yuki", "Raj", "Priya", "Ahmed", "Fatima",
+    "Carlos", "Sofia", "Hans", "Ingrid", "Liam", "Olivia", "Noah", "Ava",
+)
+
+LAST_NAMES: tuple[str, ...] = (
+    "Smith", "Johnson", "Williams", "Brown", "Jones", "Garcia", "Miller", "Davis",
+    "Rodriguez", "Martinez", "Hernandez", "Lopez", "Gonzalez", "Wilson", "Anderson", "Thomas",
+    "Taylor", "Moore", "Jackson", "Martin", "Lee", "Perez", "Thompson", "White",
+    "Harris", "Sanchez", "Clark", "Ramirez", "Lewis", "Robinson", "Walker", "Young",
+    "Allen", "King", "Wright", "Scott", "Torres", "Nguyen", "Hill", "Flores",
+    "Green", "Adams", "Nelson", "Baker", "Hall", "Rivera", "Campbell", "Mitchell",
+    "Carter", "Roberts", "Chen", "Tan", "Kumar", "Patel", "Khan", "Ali",
+    "Muller", "Schmidt", "Rossi", "Dubois", "Kowalski", "Ivanov", "Suzuki", "Tanaka",
+)
+
+ROLE_POOL: tuple[str, ...] = (
+    "Account Holder",
+    "Authorized Signatory",
+    "Branch Manager",
+    "Bank Representative",
+    "Bank Officer",
+    "Loan Officer",
+    "Notary Public",
+    "Guarantor",
+    "Co-Signer",
+    "Compliance Officer",
+    "First Authorised Signatory",
+    "Second Authorised Signatory",
+)
+
+
+def generate_name(rng: random.Random) -> str:
+    """Generate a deterministic synthetic full name from a seeded RNG."""
+    return f"{rng.choice(FIRST_NAMES)} {rng.choice(LAST_NAMES)}"
+
+
+def generate_role(rng: random.Random) -> str:
+    """Generate a deterministic synthetic role from a seeded RNG."""
+    return rng.choice(ROLE_POOL)

src/utils/random_utils.py

@@ -0,0 +1,96 @@
+"""Deterministic random-state management.
+
+The generator must produce byte-identical output for a given ``(master_seed,
+sample_index)`` pair regardless of process/thread scheduling, batch size, or
+worker count. To guarantee this we never share a single global RNG across
+samples or pipeline stages. Instead, every stage of every sample draws from
+an independently *derived* RNG whose seed is a pure function of
+``(master_seed, sample_index, stage_name)``.
+
+This makes the pipeline safe for multiprocessing: worker N generating sample
+57 produces exactly the same random draws as a single-process run would have,
+because nothing depends on execution order.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import random
+from typing import Any
+
+import numpy as np
+
+_MOD32 = 2**32
+
+
+def derive_seed(master_seed: int, *parts: Any) -> int:
+    """Derive a deterministic 32-bit seed from a master seed and arbitrary parts.
+
+    Uses SHA-256 over the concatenated string representation of all parts so
+    that the mapping is stable across Python versions and processes (unlike
+    Python's salted ``hash()``).
+
+    Args:
+        master_seed: The top-level seed configured by the user.
+        *parts: Any number of hashable/stringifiable disambiguators, e.g.
+            sample index and pipeline stage name.
+
+    Returns:
+        A non-negative integer in ``[0, 2**32)`` suitable for seeding
+        ``numpy.random.Generator`` or ``random.Random``.
+    """
+    key = f"{master_seed}|" + "|".join(str(p) for p in parts)
+    digest = hashlib.sha256(key.encode("utf-8")).digest()
+    return int.from_bytes(digest[:4], byteorder="big") % _MOD32
+
+
+class SeedManager:
+    """Provides independent, deterministic RNGs for each pipeline stage of one sample.
+
+    Example:
+        >>> sm = SeedManager(master_seed=42, sample_index=7)
+        >>> rng = sm.numpy_rng("placement")
+        >>> rng.uniform(0, 1)
+    """
+
+    def __init__(self, master_seed: int, sample_index: int) -> None:
+        self.master_seed = master_seed
+        self.sample_index = sample_index
+
+    def seed_for(self, stage: str) -> int:
+        """Return the deterministic integer seed for a named pipeline stage."""
+        return derive_seed(self.master_seed, self.sample_index, stage)
+
+    def numpy_rng(self, stage: str) -> np.random.Generator:
+        """Return a fresh ``numpy.random.Generator`` (PCG64) seeded for ``stage``."""
+        return np.random.default_rng(self.seed_for(stage))
+
+    def python_rng(self, stage: str) -> random.Random:
+        """Return a fresh ``random.Random`` seeded for ``stage``."""
+        return random.Random(self.seed_for(stage))
+
+
+def resolve_scalar_or_range(value: Any, rng: np.random.Generator) -> float:
+    """Resolve a config parameter that is either a fixed scalar or a ``{min, max}`` range.
+
+    Args:
+        value: Either a plain number, or an object/mapping exposing ``min``
+            and ``max`` attributes/keys (a :class:`~src.config.schema.Range`
+            or an equivalent dict).
+        rng: The seeded generator to draw from when ``value`` is a range.
+
+    Returns:
+        A resolved float value.
+    """
+    if isinstance(value, (int, float)):
+        return float(value)
+    if isinstance(value, dict) and "min" in value and "max" in value:
+        lo, hi = float(value["min"]), float(value["max"])
+        return float(rng.uniform(lo, hi)) if hi > lo else lo
+    # Pydantic Range model (duck-typed access)
+    lo = getattr(value, "min", None)
+    hi = getattr(value, "max", None)
+    if lo is not None and hi is not None:
+        lo, hi = float(lo), float(hi)
+        return float(rng.uniform(lo, hi)) if hi > lo else lo
+    raise TypeError(f"Cannot resolve scalar-or-range value: {value!r}")

src/utils/transform_utils.py

@@ -0,0 +1,49 @@
+"""Shared geometric raster transforms used by both placement and augmentation."""
+
+from __future__ import annotations
+
+import cv2
+import numpy as np
+
+
+def rotate_and_scale_rgba(rgba: np.ndarray, angle_deg: float, scale: float = 1.0) -> np.ndarray:
+    """Rotate (and optionally scale) an RGBA image about its own center.
+
+    The output canvas automatically expands to tightly bound the rotated
+    rectangle so no content is clipped; newly exposed corners are fully
+    transparent.
+    """
+    h, w = rgba.shape[:2]
+    if h == 0 or w == 0:
+        return rgba
+    cx, cy = w / 2.0, h / 2.0
+    matrix = cv2.getRotationMatrix2D((cx, cy), angle_deg, scale)
+    cos, sin = abs(matrix[0, 0]), abs(matrix[0, 1])
+    new_w = max(int(np.ceil(h * sin + w * cos)), 1)
+    new_h = max(int(np.ceil(h * cos + w * sin)), 1)
+    matrix[0, 2] += new_w / 2.0 - cx
+    matrix[1, 2] += new_h / 2.0 - cy
+    return cv2.warpAffine(
+        rgba, matrix, (new_w, new_h),
+        flags=cv2.INTER_LINEAR, borderMode=cv2.BORDER_CONSTANT, borderValue=(0, 0, 0, 0),
+    )
+
+
+def smooth_noise_field(shape: tuple[int, int], rng: np.random.Generator, blur_frac: float = 0.08) -> np.ndarray:
+    """Generate a smooth, low-frequency noise field in ``[0, 1]`` of the given ``(h, w)`` shape.
+
+    Built by upsampling coarse random noise, which is a fast and dependency-free
+    stand-in for Perlin/simplex noise -- adequate for subtle shading effects
+    like paper texture, discoloration, and ink fading.
+    """
+    h, w = shape
+    coarse_h = max(int(h * blur_frac), 4)
+    coarse_w = max(int(w * blur_frac), 4)
+    coarse = rng.uniform(0.0, 1.0, size=(coarse_h, coarse_w)).astype(np.float32)
+    field = cv2.resize(coarse, (w, h), interpolation=cv2.INTER_CUBIC)
+    field = cv2.GaussianBlur(field, (0, 0), sigmaX=max(w, h) * 0.01 + 1)
+    field -= field.min()
+    max_val = field.max()
+    if max_val > 1e-6:
+        field /= max_val
+    return field

src/verification/case_types.py

@@ -0,0 +1,55 @@
+"""The verification test-case taxonomy: ``case_type`` -> ground-truth verdict.
+
+Each :class:`CaseSpec` encodes one row of the signature-verification test
+plan: what should actually be rendered into the target signature box
+(``signature_mode``), whether a companion box on the same page should also
+be filled with its own correctly-authorized signature (``fill_companion`` --
+only meaningful for the multi-signer-context cases), and the ground-truth
+``verdict``/``reject_code`` a downstream verifier is expected to produce.
+
+Driven by the existing ``quality.case_type`` config field (see
+``configs/examples/hard_degraded.yaml`` for its prior, simpler use as a
+plain metadata label) -- setting it to one of the codes below switches
+:meth:`~src.generator.GeneratorContext.run_sample` into scenario-driven
+generation. Any other value (or ``None``) leaves generation entirely
+unaffected.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+SignatureMode = str  # one of the _SIGNATURE_MODES below, kept as a plain str for simplicity
+
+NO_SIGNATURE = "NO_SIGNATURE"
+IDENTITY_MISMATCH = "IDENTITY_MISMATCH"
+ROLE_MISMATCH = "ROLE_MISMATCH"
+REQUIRED_SIGNER_ABSENT = "REQUIRED_SIGNER_ABSENT"
+
+
+@dataclass(frozen=True)
+class CaseSpec:
+    """One row of the verification test-case taxonomy."""
+
+    code: str
+    description: str
+    verdict: str  # "PASS" | "REJECT"
+    reject_code: "str | None"
+    signature_mode: SignatureMode
+    fill_companion: bool = False
+
+
+CASE_TABLE: dict[str, CaseSpec] = {
+    "1a": CaseSpec("1a", "Correct signer signs normally", "PASS", None, "genuine_correct"),
+    "1b": CaseSpec("1b", "Correct signer, natural pen variation applied", "PASS", None, "genuine_variation"),
+    "1c": CaseSpec("1c", "Multi-signer form, both sign correctly", "PASS", None, "genuine_correct", fill_companion=True),
+    "1d": CaseSpec("1d", "Correct signer, scan degraded to test robustness", "PASS", None, "genuine_correct"),
+    "2a": CaseSpec("2a", "Box left completely blank", "REJECT", NO_SIGNATURE, "blank"),
+    "2b": CaseSpec("2b", "Printed/typed name only, no handwriting", "REJECT", NO_SIGNATURE, "printed_text"),
+    "3a": CaseSpec("3a", "Wrong real person signs the box", "REJECT", IDENTITY_MISMATCH, "wrong_signer_genuine"),
+    "3b": CaseSpec("3b", "Skilled-forgery sample used", "REJECT", IDENTITY_MISMATCH, "forged_skilled"),
+    "4a": CaseSpec("4a", "Authorized signer, but wrong role's box", "REJECT", ROLE_MISMATCH, "role_swap", fill_companion=True),
+    "4b": CaseSpec("4b", "Signer from a different form entirely", "REJECT", ROLE_MISMATCH, "foreign_template_signer", fill_companion=True),
+    "5a": CaseSpec("5a", "Required signer's box left empty", "REJECT", REQUIRED_SIGNER_ABSENT, "blank", fill_companion=True),
+    "5b": CaseSpec("5b", "Someone else signs in the required signer's place", "REJECT", REQUIRED_SIGNER_ABSENT, "wrong_signer_genuine", fill_companion=True),
+}

src/verification/registry.py

@@ -0,0 +1,95 @@
+"""Deterministic authorized-signer identity registry.
+
+The base generation pipeline has no notion of "the correct signer for this
+box" -- it just draws a random genuine signature for whichever box was
+picked. Every verification case type (see :mod:`src.verification.case_types`)
+hinges on comparing an *authorized* identity against an *actual* one, so this
+module derives that ground truth purely from ``(master_seed, template_id,
+box_id)`` via :func:`~src.utils.random_utils.derive_seed` -- no persisted
+state, fully reproducible, consistent with the rest of the pipeline's
+seeding philosophy.
+"""
+
+from __future__ import annotations
+
+import random
+import re
+
+from src.signatures.signature_dataset import SignatureDataset
+from src.templates.template_loader import TemplateLoader
+from src.utils.names import generate_name
+from src.utils.random_utils import derive_seed
+
+# Signer groups auto-derived by SignatureDataset (CEDAR filenames, or no
+# metadata.csv identity override) look like "signer_0014" and carry no real
+# name -- those get a generated display name. Groups sourced from
+# metadata.csv (e.g. "Priya Sharma") already *are* a real name.
+_AUTO_GROUP_PATTERN = re.compile(r"^signer_\d+$")
+
+
+class SignerIdentityRegistry:
+    """Resolves ground-truth authorized signer identities for template boxes.
+
+    Example:
+        >>> registry = SignerIdentityRegistry(template_loader, signature_dataset, master_seed=1234)
+        >>> registry.authorized_signer_group("bank_doc_03", "sig1")
+        'signer_0014'
+    """
+
+    def __init__(self, template_loader: TemplateLoader, signature_dataset: SignatureDataset, master_seed: int) -> None:
+        self.template_loader = template_loader
+        self.signature_dataset = signature_dataset
+        self.master_seed = master_seed
+        self._signer_groups = signature_dataset.signer_groups()
+
+    def authorized_signer_group(self, template_id: str, box_id: str) -> str:
+        """Return the deterministic ground-truth authorized signer for one (template, box)."""
+        seed = derive_seed(self.master_seed, template_id, box_id, "authorized_signer")
+        idx = seed % len(self._signer_groups)
+        return self._signer_groups[idx]
+
+    def foreign_authorized(self, exclude_template_id: str) -> tuple[str, str, str]:
+        """Return ``(signer_group, template_id, box_id)`` for a box on a *different* template.
+
+        Used for the "signer from a different form entirely" scenario: the
+        identity is a legitimately authorized signer, just not for this
+        document.
+        """
+        templates = self.template_loader.discover()
+        candidate_ids = sorted(tid for tid in templates if tid != exclude_template_id)
+        if not candidate_ids:
+            # Only one template discovered; fall back to a different box on the same one.
+            candidate_ids = [exclude_template_id]
+
+        seed = derive_seed(self.master_seed, exclude_template_id, "foreign_template")
+        foreign_template_id = candidate_ids[seed % len(candidate_ids)]
+
+        boxes = templates[foreign_template_id].annotation.pages[0].signature_boxes
+        box_seed = derive_seed(self.master_seed, exclude_template_id, foreign_template_id, "foreign_box")
+        box = boxes[box_seed % len(boxes)]
+
+        return self.authorized_signer_group(foreign_template_id, box.id), foreign_template_id, box.id
+
+    def random_wrong_signer_group(self, rng: random.Random, exclude_group: str) -> str:
+        """Return a uniformly random signer group other than ``exclude_group``."""
+        pool = [g for g in self._signer_groups if g != exclude_group]
+        return rng.choice(pool)
+
+    def display_name(self, signer_group: str) -> str:
+        """Return a stable, human-readable display name for a signer group.
+
+        Groups sourced from ``dataset/metadata.csv`` (e.g. ``"Priya Sharma"``)
+        already carry a real name and are returned as-is. Anonymous
+        auto-derived groups (e.g. ``"signer_0014"``, from the bundled CEDAR
+        dataset) get a generated name, stable across an entire run so a
+        benchmark built from many samples reads as consistent identities
+        rather than a fresh random name every time.
+        """
+        if not _AUTO_GROUP_PATTERN.match(signer_group):
+            return signer_group
+        seed = derive_seed(self.master_seed, signer_group, "display_name")
+        return generate_name(random.Random(seed))
+
+    def script_for(self, signer_group: str) -> str:
+        """Return the handwriting script (e.g. ``"latin"``, ``"hindi"``, ``"bengali"``) for a signer group."""
+        return self.signature_dataset.script_for_group(signer_group)

src/visualization/__init__.py

@@ -0,0 +1 @@
+"""Debug visualization figures for generated samples."""

src/visualization/visualizer.py

@@ -0,0 +1,137 @@
+"""Renders a multi-panel debug figure for one generated sample.
+
+Shows the full rendered document with the target box, detected bounding
+box, and detected polygon overlaid; a crop of the signature field; a mask
+reconstructed from the detected ink polygon; the resolved coverage metrics;
+and a difficulty-component breakdown bar chart.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import cv2
+import matplotlib
+
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+import numpy as np
+
+from src.utils.logging_utils import get_logger
+
+logger = get_logger(__name__)
+
+
+def _draw_overlays(image: np.ndarray, metadata: dict[str, Any]) -> np.ndarray:
+    out = image.copy()
+    geometry = metadata["geometry"]
+
+    def as_int_box(box):
+        return tuple(int(round(v)) for v in box)
+
+    tb = as_int_box(geometry["target_box"])
+    ab = as_int_box(geometry["actual_box"])
+    cv2.rectangle(out, (tb[0], tb[1]), (tb[2], tb[3]), (0, 200, 0), 2)
+    cv2.rectangle(out, (ab[0], ab[1]), (ab[2], ab[3]), (30, 80, 230), 2)
+
+    polygon = geometry.get("signature_polygon_px") or []
+    if len(polygon) >= 3:
+        pts = np.array(polygon, dtype=np.int32).reshape(-1, 1, 2)
+        cv2.polylines(out, [pts], isClosed=True, color=(220, 30, 30), thickness=2)
+
+    return out
+
+
+def _crop_region(image: np.ndarray, box: list, pad: int = 25) -> np.ndarray:
+    h, w = image.shape[:2]
+    x1, y1, x2, y2 = (int(round(v)) for v in box)
+    x1, y1 = max(x1 - pad, 0), max(y1 - pad, 0)
+    x2, y2 = min(x2 + pad, w), min(y2 + pad, h)
+    if x2 <= x1 or y2 <= y1:
+        return image
+    return image[y1:y2, x1:x2]
+
+
+def _reconstruct_mask(shape: tuple[int, int], box: list, polygon: list) -> np.ndarray:
+    mask = np.zeros(shape, dtype=np.uint8)
+    if len(polygon) >= 3:
+        pts = np.array(polygon, dtype=np.int32).reshape(-1, 1, 2)
+        cv2.fillPoly(mask, [pts], 255)
+    x1, y1, x2, y2 = (int(round(v)) for v in box)
+    pad = 25
+    x1c, y1c = max(x1 - pad, 0), max(y1 - pad, 0)
+    x2c, y2c = min(x2 + pad, shape[1]), min(y2 + pad, shape[0])
+    if x2c <= x1c or y2c <= y1c:
+        return mask
+    return mask[y1c:y2c, x1c:x2c]
+
+
+def save_visualization(path: "str | Path", final_image: np.ndarray, metadata: dict[str, Any]) -> None:
+    """Render and save a multi-panel debug figure for one generated sample.
+
+    Args:
+        path: Output PNG path.
+        final_image: The fully rendered (and augmented) document.
+        metadata: The sample's full metadata dict, as built by
+            :class:`~src.metadata.metadata_exporter.MetadataExporter`.
+    """
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    geometry = metadata["geometry"]
+    difficulty = metadata["difficulty"]
+    metrics = metadata["metrics"]
+
+    overlaid = _draw_overlays(final_image, metadata)
+    crop = _crop_region(final_image, geometry["actual_box"])
+    mask = _reconstruct_mask(final_image.shape[:2], geometry["actual_box"], geometry["signature_polygon_px"])
+
+    fig = plt.figure(figsize=(15, 9.5), dpi=110)
+    fig.suptitle(
+        f"{metadata['document_id']}  |  template={metadata['template']}  |  box={metadata['geometry']['target_box']}",
+        x=0.02, ha="left", fontsize=11, family="monospace",
+    )
+    grid = fig.add_gridspec(2, 3, width_ratios=[2.0, 1.0, 1.0], height_ratios=[1.0, 1.0])
+
+    ax_full = fig.add_subplot(grid[:, 0])
+    ax_full.imshow(overlaid)
+    ax_full.axis("off")
+
+    ax_crop = fig.add_subplot(grid[0, 1])
+    ax_crop.imshow(crop)
+    ax_crop.set_title("Signature field (cropped)")
+    ax_crop.axis("off")
+
+    ax_mask = fig.add_subplot(grid[0, 2])
+    ax_mask.imshow(mask, cmap="gray")
+    ax_mask.set_title("Detected ink mask")
+    ax_mask.axis("off")
+
+    ax_metrics = fig.add_subplot(grid[1, 1])
+    ax_metrics.axis("off")
+    metric_lines = [
+        f"box_coverage_pct:  {metrics['box_coverage_pct']:.2f}",
+        f"containment_pct:   {metrics['containment_pct']:.2f}",
+        f"ink_fill_ratio:    {metrics['ink_fill_ratio']:.3f}",
+        f"polygon_overlap:   {metrics['polygon_overlap_proxy']:.3f}",
+        f"dist_from_center:  {metrics['distance_from_box_center_px']:.1f}px",
+        f"margin_util:       {metrics['margin_utilization']:.3f}",
+        f"mean_dark_int:     {metrics['mean_dark_intensity']:.1f}",
+        f"gray_stddev:       {metrics['gray_stddev']:.1f}",
+        f"signer:            {metadata['signer']['name']} ({metadata['signer']['role']})",
+    ]
+    ax_metrics.text(0.0, 1.0, "\n".join(metric_lines), va="top", ha="left", family="monospace", fontsize=9)
+    ax_metrics.set_title("Coverage metrics")
+
+    ax_diff = fig.add_subplot(grid[1, 2])
+    components = ["misplacement", "whitespace", "faintness", "smallness", "low_texture"]
+    values = [difficulty[c] for c in components]
+    colors = ["#d62728" if v >= 0.66 else "#ff7f0e" if v >= 0.33 else "#2ca02c" for v in values]
+    ax_diff.barh(components, values, color=colors)
+    ax_diff.set_xlim(0, 1)
+    ax_diff.set_title(f"Difficulty: {difficulty['score']:.3f} ({difficulty['tier']})")
+
+    fig.tight_layout(rect=(0.0, 0.0, 1.0, 0.94))
+    fig.savefig(path)
+    plt.close(fig)