Add files using upload-large-folder tool

scripts/build_degradation_slides.py

@@ -0,0 +1,306 @@
+#!/usr/bin/env python
+"""Append a before/after slide per augmentation effect, plus normal- and
+extreme-case multi-degradation slides, to Metrics_Thresholds_Formulas.pptx.
+
+Reuses the assets written by generate_before_after_assets.py and
+generate_case_assets.py (run those first). New slides replicate the deck's
+existing visual language exactly (navy header bar, orange accent line, teal
+section label, Calibri/Consolas body text, bottom-right page number) so they
+read as part of the same deck rather than a bolt-on.
+
+The new slides are inserted as a new section 8 ("Degradation gallery") and
+section 9 ("Multi-degradation cases"), placed right before the closing "Key
+takeaways" slide, and the Agenda slide (slide 2) is extended with the two new
+entries. A one-time backup of the original file is kept alongside it.
+
+Usage:
+    python scripts/build_degradation_slides.py
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+import shutil
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from pptx import Presentation
+from pptx.dml.color import RGBColor
+from pptx.enum.shapes import MSO_SHAPE
+from pptx.enum.text import MSO_ANCHOR, PP_ALIGN
+from pptx.util import Emu, Pt
+from PIL import Image
+
+from scripts.generate_before_after_assets import (
+    ALL_EFFECTS, DISPLAY_NAME, ZOOM_EFFECTS,
+)
+from scripts.generate_multiple_degradation_extreme_gallery import _fmt_effect
+
+ROOT = Path(__file__).resolve().parents[1]
+PPTX_PATH = ROOT / "Metrics_Thresholds_Formulas.pptx"
+BACKUP_PATH = ROOT / "Metrics_Thresholds_Formulas.backup.pptx"
+DEG_ROOT = ROOT / "degradation"
+
+# ---------------------------------------------------------------- palette --
+NAVY, TEAL, ORANGE = "0F2A43", "1B7A7A", "E07A2C"
+LIGHT_TEAL, GRAY, LIGHT_BG, TEXT_DARK, WHITE = "9BC5C5", "6B767C", "F4F7F8", "222A30", "FFFFFF"
+
+
+def rgb(hexstr: str) -> RGBColor:
+    return RGBColor.from_string(hexstr)
+
+
+# ------------------------------------------------------------- geometry ---
+SLIDE_W, SLIDE_H = Emu(12191695), Emu(6858000)
+HEADER_H, ACCENT_H = Emu(1051560), Emu(38100)
+TITLE_X = Emu(502920)
+CONTENT_X, CONTENT_W = Emu(640080), Emu(10881360)
+FOOTER_X, FOOTER_Y = Emu(11475720), Emu(6510528)
+FOOTER_W, FOOTER_H = Emu(640080), Emu(274320)
+
+LEFT_X, RIGHT_X = Emu(640080), Emu(6263640)
+COL_W = Emu(5257800)
+LABEL_Y, LABEL_H = Emu(1554480), Emu(365760)
+IMG_Y = Emu(LABEL_Y + LABEL_H + Emu(91440))
+
+CAPTION_Y = Emu(1150000)
+CAPTION_H = Emu(320040)
+
+# ------------------------------------------------------ formula captions --
+FORMULAS = {
+    "rotation": "extra_deg = U(-1,1) × strength × 8.0",
+    "stroke_dilation": "ksize = round(1 + strength×5)  [odd]",
+    "ink_fading": "mult = clip(1 − strength×(1−field)×0.9, .05, 1)",
+    "ink_bleed": "ksize = round(1+strength×4); halo floor = .35+.35×strength",
+    "motion_blur": "length = round(3 + strength×16)",
+    "gaussian_blur": "sigma = 0.2 + strength×2.2",
+    "perspective": "scale = 0.01 + strength×0.09",
+    "contrast": "contrast_limit = ±(strength×0.45)",
+    "gamma": "delta = round(strength×45); gamma_limit = (100−delta, 100+delta), lo≥40",
+    "coffee_stain": "n_blobs = 1+randint(0,1+round(strength×3)); opacity = .10+.30×strength",
+    "stain": "radius = (.06+.16×strength)×min(w,h); opacity scales with strength",
+    "shadow": "darkness = 0.15+0.55×strength; band/radius/fold-width scale with strength",
+    "crumple": "amplitude = strength×min(w,h)×0.015",
+    "discoloration": "tint strength scales with strength per tone",
+    "page_tilt": "angle = U(-1,1) × (1.5 + strength×6.5)",
+    "dust": "n_specks = (h×w)×0.00003×(1+strength×6)",
+    "scanner_streaks": "n_streaks = 1+int(strength×6)",
+    "scanner_noise": "GaussNoise std = 0.01 + strength×0.12",
+    "salt_pepper": "amount = 0.002 + strength×0.09",
+    "jpeg_compression": "quality = randint(min_quality, max_quality) — NOT driven by strength",
+}
+
+
+def short_list(names: list[str], limit: int = 8) -> str:
+    if len(names) <= limit:
+        return ", ".join(names) if names else "none"
+    return ", ".join(names[:limit]) + f", +{len(names) - limit} more"
+
+
+# ----------------------------------------------------------- primitives ---
+def add_rect(slide, x, y, w, h, color: str):
+    shp = slide.shapes.add_shape(MSO_SHAPE.RECTANGLE, x, y, w, h)
+    shp.fill.solid()
+    shp.fill.fore_color.rgb = rgb(color)
+    shp.line.fill.background()
+    return shp
+
+
+def add_text(
+    slide, x, y, w, h, text, size, color, *, bold=False, font="Calibri",
+    align=PP_ALIGN.LEFT, anchor=None, word_wrap=True,
+):
+    tb = slide.shapes.add_textbox(x, y, w, h)
+    tf = tb.text_frame
+    tf.margin_left = tf.margin_right = tf.margin_top = tf.margin_bottom = 0
+    tf.word_wrap = word_wrap
+    if anchor is not None:
+        tf.vertical_anchor = anchor
+    lines = text.split("\n")
+    for i, line in enumerate(lines):
+        p = tf.paragraphs[0] if i == 0 else tf.add_paragraph()
+        p.alignment = align
+        run = p.add_run()
+        run.text = line
+        run.font.size = Pt(size)
+        run.font.bold = bold
+        run.font.name = font
+        run.font.color.rgb = rgb(color)
+    return tb
+
+
+def add_bg(slide):
+    add_rect(slide, Emu(0), Emu(0), SLIDE_W, SLIDE_H, WHITE)
+
+
+def add_header(slide, section_label: str, title: str, page_num: int):
+    add_rect(slide, Emu(0), Emu(0), SLIDE_W, HEADER_H, NAVY)
+    add_rect(slide, Emu(0), HEADER_H, SLIDE_W, ACCENT_H, ORANGE)
+    add_text(slide, TITLE_X, Emu(128016), Emu(9144000), Emu(274320), section_label, 12, LIGHT_TEAL, bold=True)
+    add_text(slide, TITLE_X, Emu(384048), Emu(10515600), Emu(594360), title, 28, WHITE, bold=True)
+    add_text(
+        slide, FOOTER_X, FOOTER_Y, FOOTER_W, FOOTER_H, str(page_num), 11, GRAY,
+        align=PP_ALIGN.RIGHT,
+    )
+
+
+def fit_picture(slide, img_path: Path, box_x, box_y, box_w, box_h):
+    iw, ih = Image.open(img_path).size
+    scale = min(box_w / iw, box_h / ih)
+    disp_w, disp_h = int(iw * scale), int(ih * scale)
+    left = int(box_x + (box_w - disp_w) / 2)
+    top = int(box_y + (box_h - disp_h) / 2)
+    slide.shapes.add_picture(str(img_path), left, top, width=disp_w, height=disp_h)
+
+
+def add_panel_label(slide, x, color, text):
+    add_rect(slide, x, LABEL_Y, COL_W, LABEL_H, color)
+    add_text(
+        slide, x, LABEL_Y, COL_W, LABEL_H, text, 14, WHITE, bold=True,
+        align=PP_ALIGN.CENTER, anchor=MSO_ANCHOR.MIDDLE, word_wrap=False,
+    )
+
+
+# -------------------------------------------------------------- slides ----
+def build_before_after_slide(prs, layout, effect: str, page_num: int, manifest: dict):
+    slide = prs.slides.add_slide(layout)
+    add_bg(slide)
+    add_header(slide, "8. DEGRADATION GALLERY", DISPLAY_NAME[effect], page_num)
+
+    rec = manifest[effect]
+    resolved = _fmt_effect(effect, {"strength": rec["strength"], "params": rec["params"] or {}})
+    caption = (
+        f"{FORMULAS[effect]}     |     resolved: {resolved}     |     "
+        f"difficulty after = {rec['difficulty_score']:.3f} ({rec['difficulty_tier']})"
+    )
+    add_text(slide, CONTENT_X, CAPTION_Y, CONTENT_W, CAPTION_H, caption, 12, GRAY, font="Consolas")
+
+    add_panel_label(slide, LEFT_X, TEAL, "BEFORE  -  clean render")
+    add_panel_label(slide, RIGHT_X, ORANGE, f"AFTER  -  {DISPLAY_NAME[effect]} (strength={rec['strength']:.2f})")
+
+    img_bottom = Emu(6100000)
+    img_h = Emu(img_bottom - IMG_Y)
+    before_name = "before_zoom.png" if effect in ZOOM_EFFECTS else "before.png"
+    after_name = "after_zoom.png" if effect in ZOOM_EFFECTS else "after.png"
+    fit_picture(slide, DEG_ROOT / effect / before_name, LEFT_X, IMG_Y, COL_W, img_h)
+    fit_picture(slide, DEG_ROOT / effect / after_name, RIGHT_X, IMG_Y, COL_W, img_h)
+    return slide
+
+
+def build_case_slide(prs, layout, kind: str, page_num: int):
+    slide = prs.slides.add_slide(layout)
+    add_bg(slide)
+    title = "Normal-severity combinations" if kind == "normal" else "Extreme-severity combinations"
+    add_header(slide, "9. MULTI-DEGRADATION CASES", title, page_num)
+
+    if kind == "normal":
+        folder = ROOT / "multiple_degradation" / "case_assets"
+        subtitle = (
+            "configs/generate.yaml -- every effect independently rolls its own realistic "
+            "probability per sample (mixed, moderate combinations)"
+        )
+        color = TEAL
+    else:
+        folder = ROOT / "multiple_degradation_extreme" / "case_assets"
+        subtitle = (
+            "worst case -- every effect probability=0.85, strength 0.7-1.0, plus heavy "
+            "misplacement / faint+blurred ink (see scripts/generate_multiple_degradation_extreme_gallery.py)"
+        )
+        color = ORANGE
+
+    manifest = json.loads((folder / "case_manifest.json").read_text())
+    add_text(slide, CONTENT_X, CAPTION_Y, CONTENT_W, CAPTION_H, subtitle, 12, GRAY, font="Consolas")
+
+    img_bottom = Emu(5850000)
+    img_h = Emu(img_bottom - IMG_Y)
+    cap_y = Emu(img_bottom + Emu(45720))
+    cap_h = Emu(600000)
+
+    for i, x in enumerate((LEFT_X, RIGHT_X)):
+        key = f"case_{i + 1}"
+        rec = manifest[key]
+        add_panel_label(slide, x, color, f"Sample {i + 1}  -  {rec['n_applied']}/{rec['n_total']} effects applied")
+        fit_picture(slide, folder / f"{key}.png", x, IMG_Y, COL_W, img_h)
+        cap = (
+            f"difficulty = {rec['difficulty_score']:.3f} ({rec['difficulty_tier']})   |   "
+            f"placement: rot={rec['placement']['rotation_deg']:.1f} deg  "
+            f"scale={rec['placement']['scale_factor']:.2f}  misplaced={rec['placement']['misplaced']}\n"
+            f"applied: {short_list(rec['applied_effects'])}"
+        )
+        add_text(slide, x, cap_y, COL_W, cap_h, cap, 10, TEXT_DARK, font="Consolas")
+    return slide
+
+
+# ---------------------------------------------------------- agenda edit ---
+def extend_agenda(prs):
+    slide = prs.slides[1]
+    target = None
+    for shape in slide.shapes:
+        if shape.name == "TextBox 7":
+            target = shape
+            break
+    if target is None:
+        print("WARNING: could not find agenda TextBox 7 -- skipping agenda update")
+        return
+
+    tf = target.text_frame
+    n_original = len(tf.paragraphs)
+    last_p = tf.paragraphs[-1]._p
+    new_texts = (
+        "8.  Degradation gallery — before & after, all 20 effects",
+        "9.  Multi-degradation cases — normal vs. extreme severity",
+    )
+    for text in new_texts:
+        new_p = copy.deepcopy(last_p)
+        run_elm = new_p.findall(".//{http://schemas.openxmlformats.org/drawingml/2006/main}t")
+        run_elm[0].text = text
+        last_p.addnext(new_p)
+        last_p = new_p
+
+    # Shape height doesn't clip a top-anchored textbox -- text simply overflows past
+    # it -- so what actually matters is total rendered text height staying inside the
+    # slide. 9 lines at the original 22pt ran ~24pt past the bottom edge, so shrink
+    # every run down to 20pt (measured to comfortably clear the slide bottom).
+    for para in tf.paragraphs:
+        for run in para.runs:
+            run.font.size = Pt(20)
+
+
+# ---------------------------------------------------------------- main ----
+def main():
+    if not BACKUP_PATH.exists():
+        shutil.copy2(PPTX_PATH, BACKUP_PATH)
+        print(f"Backed up original deck -> {BACKUP_PATH}")
+
+    manifest = json.loads((DEG_ROOT / "before_after_manifest.json").read_text())
+
+    prs = Presentation(str(PPTX_PATH))
+    layout = prs.slides[2].slide_layout  # "Blank" layout used by all content slides
+
+    sld_id_lst = prs.slides._sldIdLst
+    closing_sld_id = sld_id_lst[-1]  # "Key takeaways" slide, must stay last
+
+    extend_agenda(prs)
+
+    page_num = 19
+    for effect in ALL_EFFECTS:
+        build_before_after_slide(prs, layout, effect, page_num, manifest)
+        page_num += 1
+
+    build_case_slide(prs, layout, "normal", page_num)
+    page_num += 1
+    build_case_slide(prs, layout, "extreme", page_num)
+    page_num += 1
+
+    sld_id_lst.remove(closing_sld_id)
+    sld_id_lst.append(closing_sld_id)
+
+    prs.save(str(PPTX_PATH))
+    print(f"Saved {PPTX_PATH} -- {len(prs.slides.__iter__.__self__._sldIdLst)} slides total")
+
+
+if __name__ == "__main__":
+    main()

scripts/degrade_cli.py

@@ -0,0 +1,279 @@
+#!/usr/bin/env python
+"""Interactive terminal wizard for generating synthetic signed documents with
+hand-picked degradation effects.
+
+A friendlier front end over main.py's --set override system: arrow-key menus
+and checkboxes instead of memorizing config dot-paths. Same pipeline underneath
+(GeneratorContext), so output is identical to what main.py would produce with
+the equivalent --set flags.
+
+Usage:
+    python scripts/degrade_cli.py
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from datetime import datetime
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+import questionary
+from questionary import Choice, Separator
+from rich.console import Console
+from rich.panel import Panel
+from rich.progress import BarColumn, Progress, SpinnerColumn, TextColumn, TimeElapsedColumn
+from rich.table import Table
+
+from src.config.loader import load_config
+from src.generator import GeneratorContext
+from src.templates.template_loader import TemplateLoader
+from src.utils.image_io import save_image_rgb
+from src.visualization.visualizer import save_visualization
+from scripts.generate_before_after_assets import ALL_EFFECTS, DISPLAY_NAME, DOCUMENT_EFFECTS, SIGNATURE_EFFECTS
+from scripts.generate_multiple_degradation_extreme_gallery import build_overrides as extreme_overrides
+
+ROOT = Path(__file__).resolve().parents[1]
+console = Console()
+
+# ---- palette, matched to Metrics_Thresholds_Formulas.pptx -----------------
+NAVY, TEAL, ORANGE, GRAY = "#0F2A43", "#1B7A7A", "#E07A2C", "#6B767C"
+
+QSTYLE = questionary.Style([
+    ("qmark", f"fg:{ORANGE} bold"),
+    ("question", "bold"),
+    ("answer", f"fg:{TEAL} bold"),
+    ("pointer", f"fg:{ORANGE} bold"),
+    ("highlighted", f"fg:{TEAL} bold"),
+    ("selected", f"fg:{TEAL}"),
+    ("instruction", f"fg:{GRAY}"),
+    ("separator", f"fg:{GRAY}"),
+])
+
+
+def banner() -> None:
+    console.print(Panel.fit(
+        "[bold white]Synthetic Signed Document Generator[/bold white]\n"
+        f"[{TEAL}]pick degradations  ->  generate  ->  inspect[/{TEAL}]",
+        border_style=TEAL, padding=(1, 4),
+    ))
+
+
+def discover_templates() -> list[tuple[str, str]]:
+    cfg = load_config()
+    loader = TemplateLoader(cfg.paths.image_dir, cfg.paths.annotations_dir)
+    loader.discover()
+    return sorted((tid, t.annotation.document_type) for tid, t in loader._templates.items())
+
+
+def valid_float01(v: str) -> "bool | str":
+    try:
+        f = float(v)
+    except ValueError:
+        return "Enter a number between 0.0 and 1.0"
+    return True if 0.0 <= f <= 1.0 else "Must be between 0.0 and 1.0"
+
+
+def valid_posint(v: str) -> "bool | str":
+    return True if v.isdigit() and int(v) > 0 else "Enter a positive whole number"
+
+
+# ------------------------------------------------------------- questions ---
+def ask_mode() -> str:
+    return questionary.select(
+        "How should degradations be applied?",
+        choices=[
+            Choice(title="Pick effects - isolated  (ONLY the chosen effects fire, nothing else)", value="isolate"),
+            Choice(title="Pick effects - mixed     (chosen effects forced on, others may also roll)", value="mixed"),
+            Choice(title="Preset - normal severity  (realistic random mix, configs/generate.yaml)", value="normal"),
+            Choice(title="Preset - extreme severity (worst case, everything cranked)", value="extreme"),
+        ],
+        style=QSTYLE,
+    ).ask()
+
+
+def ask_template() -> "str | None":
+    templates = discover_templates()
+    choices = [Choice(title="Random each sample", value=None)]
+    choices += [Choice(title=f"{tid}  ({doc_type})", value=tid) for tid, doc_type in templates]
+    return questionary.select("Which document template?", choices=choices, style=QSTYLE).ask()
+
+
+def ask_effects() -> list[str]:
+    choices = [Separator("-- signature-level --")]
+    choices += [Choice(title=DISPLAY_NAME[e], value=e) for e in SIGNATURE_EFFECTS]
+    choices += [Separator("-- document-level --")]
+    choices += [Choice(title=DISPLAY_NAME[e], value=e) for e in DOCUMENT_EFFECTS]
+    selected = questionary.checkbox(
+        "Pick degradations (space to toggle, enter to confirm)", choices=choices, style=QSTYLE,
+    ).ask()
+    if selected is None:
+        raise KeyboardInterrupt
+    if not selected:
+        console.print(f"[{ORANGE}]Pick at least one effect.[/{ORANGE}]")
+        return ask_effects()
+    return selected
+
+
+def ask_strengths(effects: list[str]) -> dict[str, float]:
+    global_raw = questionary.text(
+        "Strength for all selected effects (0.0-1.0)", default="0.75",
+        validate=valid_float01, style=QSTYLE,
+    ).ask()
+    global_strength = float(global_raw)
+    strengths = {e: global_strength for e in effects}
+    if questionary.confirm("Customize strength per effect?", default=False, style=QSTYLE).ask():
+        for e in effects:
+            raw = questionary.text(
+                f"  {DISPLAY_NAME[e]} strength", default=str(global_strength),
+                validate=valid_float01, style=QSTYLE,
+            ).ask()
+            strengths[e] = float(raw)
+    return strengths
+
+
+def ask_count() -> int:
+    raw = questionary.text("How many samples?", default="3", validate=valid_posint, style=QSTYLE).ask()
+    return int(raw)
+
+
+def ask_save_viz() -> bool:
+    return questionary.confirm(
+        "Also save the debug-panel visualization (crop / mask / metrics / difficulty)?",
+        default=True, style=QSTYLE,
+    ).ask()
+
+
+def ask_output_dir() -> Path:
+    default = f"output/interactive_{datetime.now():%Y%m%d_%H%M%S}"
+    raw = questionary.text("Output folder", default=default, style=QSTYLE).ask()
+    return ROOT / raw
+
+
+# ------------------------------------------------------------ overrides ----
+def build_pick_overrides(mode: str, template: "str | None", effects: list[str], strengths: dict[str, float]) -> list[str]:
+    overrides = ["generation.run_validation=false"]
+    if template:
+        overrides.append(f"document.template={template}")
+
+    if mode == "isolate":
+        for name in ALL_EFFECTS:
+            on = name in effects
+            overrides.append(f"augmentation.{name}.enabled={'true' if on else 'false'}")
+            overrides.append(f"augmentation.{name}.probability={'1.0' if on else '0.0'}")
+        for name in effects:
+            overrides.append(f"augmentation.{name}.strength={strengths[name]}")
+    else:  # mixed
+        for name in effects:
+            overrides.append(f"augmentation.{name}.enabled=true")
+            overrides.append(f"augmentation.{name}.probability=1.0")
+            overrides.append(f"augmentation.{name}.strength={strengths[name]}")
+    return overrides
+
+
+# ---------------------------------------------------------------- report ---
+def show_plan(mode: str, template, effects, strengths, count: int, out_dir: Path) -> None:
+    table = Table(title="Plan", title_style=f"bold {NAVY}", show_header=False, border_style=GRAY)
+    table.add_row("Mode", mode)
+    table.add_row("Template", template or "random per sample")
+    if effects:
+        table.add_row("Effects", ", ".join(f"{DISPLAY_NAME[e]} ({strengths[e]:.2f})" for e in effects))
+    table.add_row("Samples", str(count))
+    table.add_row("Output", str(out_dir))
+    console.print(table)
+
+
+def show_results(results: list[tuple[str, float, str, list[str]]], out_dir: Path) -> None:
+    table = Table(title="Results", border_style=GRAY, header_style=f"bold white on {NAVY}")
+    table.add_column("Sample")
+    table.add_column("Difficulty")
+    table.add_column("Tier")
+    table.add_column("Effects applied")
+    tier_color = {"easy": "green", "medium": ORANGE, "hard": "red"}
+    for sid, score, tier, applied in results:
+        table.add_row(
+            sid, f"{score:.3f}", f"[{tier_color.get(tier, 'white')}]{tier}[/]",
+            ", ".join(applied) if applied else "[dim]none[/dim]",
+        )
+    console.print(table)
+    console.print(f"\n[{TEAL}]Wrote {len(results)} sample(s) -> {out_dir}[/{TEAL}]")
+
+
+# ------------------------------------------------------------------ main ---
+def main() -> int:
+    banner()
+    try:
+        mode = ask_mode()
+        if mode is None:
+            raise KeyboardInterrupt
+
+        template, effects, strengths = None, [], {}
+        if mode in ("isolate", "mixed"):
+            template = ask_template()
+            effects = ask_effects()
+            strengths = ask_strengths(effects)
+
+        count = ask_count()
+        save_viz = ask_save_viz()
+        out_dir = ask_output_dir()
+
+        show_plan(mode, template, effects, strengths, count, out_dir)
+        if not questionary.confirm("Generate now?", default=True, style=QSTYLE).ask():
+            console.print("Cancelled.")
+            return 0
+
+        if mode == "normal":
+            config = load_config(
+                config_path=ROOT / "configs" / "generate.yaml",
+                overrides=["document.template=bank_doc_05", "generation.run_validation=false"],
+            )
+        elif mode == "extreme":
+            config = load_config(overrides=extreme_overrides())
+        else:
+            config = load_config(overrides=build_pick_overrides(mode, template, effects, strengths))
+
+        out_dir.mkdir(parents=True, exist_ok=True)
+        ctx = GeneratorContext(config)
+        prefix, digits = config.generation.filename_prefix, config.generation.filename_digits
+
+        results = []
+        with Progress(
+            SpinnerColumn(), TextColumn("[progress.description]{task.description}"),
+            BarColumn(complete_style=TEAL), TextColumn("{task.completed}/{task.total}"),
+            TimeElapsedColumn(), console=console,
+        ) as progress:
+            task = progress.add_task("Generating", total=count)
+            for i in range(1, count + 1):
+                metadata, final_image, _ = ctx.run_sample(i)
+                sample_id = f"{prefix}_{i:0{digits}d}"
+
+                save_image_rgb(out_dir / f"{sample_id}.png", final_image)
+                ctx.metadata_exporter.export(metadata, out_dir / f"{sample_id}.json")
+                if save_viz:
+                    save_visualization(out_dir / f"{sample_id}_viz.png", final_image, metadata)
+
+                applied = [n for n, r in metadata["augmentation"]["effects"].items() if r["applied"]]
+                results.append((sample_id, metadata["difficulty"]["score"], metadata["difficulty"]["tier"], applied))
+                progress.advance(task)
+
+        console.print()
+        show_results(results, out_dir)
+
+        if questionary.confirm("Open the output folder now?", default=True, style=QSTYLE).ask():
+            if os.name == "nt":
+                os.startfile(out_dir)  # noqa: S606
+            else:
+                console.print(str(out_dir))
+
+        return 0
+
+    except KeyboardInterrupt:
+        console.print("\n[dim]Cancelled.[/dim]")
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/generate_before_after_assets.py

@@ -0,0 +1,177 @@
+#!/usr/bin/env python
+"""Generate paired before/after images for every augmentation effect, for slides.
+
+For each of the 25 configurable effects, renders two samples that are
+identical in every respect (same template, signature, placement, box) except
+that one has every augmentation disabled ("before") and the other has just
+that one effect forced on at a fixed strength ("after"). Because placement is
+frozen and both runs share the same (seed, sample_index), the underlying
+document/signature/box are pixel-identical up to the effect itself.
+
+Signature-level effects are saved as a tight crop around the signature box
+(where the effect is visible at slide scale); document-level effects are
+saved as the full page. Also writes a JSON manifest with the resolved
+strength/params/formula description used per effect, for slide captions.
+
+Usage:
+    python scripts/generate_before_after_assets.py
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from PIL import Image
+
+from src.config.loader import load_config
+from src.generator import GeneratorContext
+from src.visualization.visualizer import _crop_region
+
+SIGNATURE_EFFECTS = [
+    "rotation", "stroke_dilation",
+    "ink_fading", "ink_bleed", "motion_blur", "gaussian_blur",
+]
+DOCUMENT_EFFECTS = [
+    "perspective", "contrast", "gamma", "coffee_stain", "stain",
+    "shadow", "crumple", "discoloration", "page_tilt", "dust", "scanner_streaks",
+    "scanner_noise", "salt_pepper", "jpeg_compression",
+]
+ALL_EFFECTS = SIGNATURE_EFFECTS + DOCUMENT_EFFECTS
+
+OUT_ROOT = Path(__file__).resolve().parents[1] / "degradation"
+TEMPLATE_ID = "bank_doc_05"
+FORCED_STRENGTH = 1.0  # max strength: matches the "range at strength=1.0" figures already on the formula slides
+SAMPLE_INDEX = 2  # picked for a bolder/higher-ink-fill signature than index 1, more visible at slide scale
+CROP_PAD = 45
+CROP_UPSCALE = 2
+
+# Purely tonal/textural document effects are nearly invisible at full-page slide
+# scale, so also cut a fixed, upscaled body-text zoom for these (kept identical
+# between before/after so the comparison is apples-to-apples). Structural effects
+# (crumple, page_tilt, perspective, shadow, scanner_streaks) already read clearly
+# on the full page and don't need one.
+ZOOM_EFFECTS = {
+    "contrast", "gamma", "coffee_stain", "stain",
+    "discoloration", "dust", "scanner_noise", "salt_pepper", "jpeg_compression",
+}
+ZOOM_BOX = (40, 110, 460, 340)  # (x1, y1, x2, y2) in full-page pixel space
+
+DISPLAY_NAME = {
+    "rotation": "Rotation jitter",
+    "stroke_dilation": "Stroke dilation",
+    "ink_fading": "Ink fading",
+    "ink_bleed": "Ink bleed",
+    "motion_blur": "Motion blur",
+    "gaussian_blur": "Gaussian blur",
+    "perspective": "Perspective warp",
+    "contrast": "Contrast shift",
+    "gamma": "Gamma shift",
+    "coffee_stain": "Coffee stain",
+    "stain": "Water / paper stain",
+    "shadow": "Shadow",
+    "crumple": "Crumple / wrinkle",
+    "discoloration": "Discoloration",
+    "page_tilt": "Page tilt",
+    "dust": "Dust specks",
+    "scanner_streaks": "Scanner streaks",
+    "scanner_noise": "Scanner noise",
+    "salt_pepper": "Salt & pepper noise",
+    "jpeg_compression": "JPEG compression",
+}
+
+
+def base_overrides() -> list[str]:
+    return [
+        f"document.template={TEMPLATE_ID}",
+        "placement.rotation_deg.min=0", "placement.rotation_deg.max=0",
+        "placement.scale_factor.min=0.85", "placement.scale_factor.max=0.85",
+        "placement.x_offset=0", "placement.y_offset=0",
+        "placement.misplacement_probability=0.0",
+        "generation.run_validation=false",
+    ]
+
+
+def all_disabled_overrides() -> list[str]:
+    overrides = base_overrides()
+    for name in ALL_EFFECTS:
+        overrides.append(f"augmentation.{name}.enabled=false")
+        overrides.append(f"augmentation.{name}.probability=0.0")
+    return overrides
+
+
+def effect_overrides(target_effect: str) -> list[str]:
+    overrides = base_overrides()
+    for name in ALL_EFFECTS:
+        is_target = name == target_effect
+        overrides.append(f"augmentation.{name}.enabled={'true' if is_target else 'false'}")
+        overrides.append(f"augmentation.{name}.probability={'1.0' if is_target else '0.0'}")
+    overrides.append(f"augmentation.{target_effect}.strength={FORCED_STRENGTH}")
+    return overrides
+
+
+def main() -> None:
+    OUT_ROOT.mkdir(parents=True, exist_ok=True)
+    manifest: dict[str, dict] = {}
+
+    baseline_config = load_config(overrides=all_disabled_overrides())
+    baseline_ctx = GeneratorContext(baseline_config)
+    baseline_meta, baseline_img, _ = baseline_ctx.run_sample(SAMPLE_INDEX)
+    box = baseline_meta["geometry"]["target_box"]
+
+    for effect in ALL_EFFECTS:
+        out_dir = OUT_ROOT / effect
+        out_dir.mkdir(parents=True, exist_ok=True)
+
+        config = load_config(overrides=effect_overrides(effect))
+        ctx = GeneratorContext(config)
+        meta, after_img, _ = ctx.run_sample(SAMPLE_INDEX)
+
+        before_img, after_img_final = baseline_img, after_img
+        if effect in SIGNATURE_EFFECTS:
+            before_out = _crop_region(before_img, box, pad=CROP_PAD)
+            after_out = _crop_region(after_img_final, box, pad=CROP_PAD)
+            before_pil = Image.fromarray(before_out)
+            after_pil = Image.fromarray(after_out)
+            before_pil = before_pil.resize(
+                (before_pil.width * CROP_UPSCALE, before_pil.height * CROP_UPSCALE), Image.LANCZOS,
+            )
+            after_pil = after_pil.resize(
+                (after_pil.width * CROP_UPSCALE, after_pil.height * CROP_UPSCALE), Image.LANCZOS,
+            )
+        else:
+            before_pil, after_pil = Image.fromarray(before_img), Image.fromarray(after_img_final)
+
+        before_pil.save(out_dir / "before.png")
+        after_pil.save(out_dir / "after.png")
+
+        if effect in ZOOM_EFFECTS:
+            x1, y1, x2, y2 = ZOOM_BOX
+            zb = Image.fromarray(before_img[y1:y2, x1:x2])
+            za = Image.fromarray(after_img_final[y1:y2, x1:x2])
+            zb = zb.resize((zb.width * CROP_UPSCALE, zb.height * CROP_UPSCALE), Image.LANCZOS)
+            za = za.resize((za.width * CROP_UPSCALE, za.height * CROP_UPSCALE), Image.LANCZOS)
+            zb.save(out_dir / "before_zoom.png")
+            za.save(out_dir / "after_zoom.png")
+
+        rec = meta["augmentation"]["effects"].get(effect, {})
+        manifest[effect] = {
+            "display_name": DISPLAY_NAME[effect],
+            "category": "signature" if effect in SIGNATURE_EFFECTS else "document",
+            "strength": rec.get("strength"),
+            "params": rec.get("params"),
+            "difficulty_score": meta["difficulty"]["score"],
+            "difficulty_tier": meta["difficulty"]["tier"],
+        }
+        print(f"[{effect}] before/after -> {out_dir}  (strength={rec.get('strength')}, params={rec.get('params')})")
+
+    manifest_path = OUT_ROOT / "before_after_manifest.json"
+    manifest_path.write_text(json.dumps(manifest, indent=2), encoding="utf-8")
+    print(f"\nWrote manifest -> {manifest_path}")
+
+
+if __name__ == "__main__":
+    main()

scripts/generate_case_assets.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python
+"""Generate plain full-page images (no dashboard overlay) for normal vs. extreme
+multi-degradation cases, for slides.
+
+Reuses the same two configurations as scripts/generate_multiple_degradation_gallery.py
+("normal": configs/generate.yaml's realistic per-effect probabilities, unmodified)
+and scripts/generate_multiple_degradation_extreme_gallery.py ("extreme": every
+effect pushed to high probability/strength plus worst-case placement/rendering),
+but writes the bare rendered page instead of the multi-panel debug figure, since
+slides just need the document image plus a short caption.
+
+Usage:
+    python scripts/generate_case_assets.py
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from PIL import Image
+
+from src.config.loader import load_config
+from src.generator import GeneratorContext
+from scripts.generate_multiple_degradation_extreme_gallery import build_overrides as extreme_overrides
+
+ROOT = Path(__file__).resolve().parents[1]
+TEMPLATE_ID = "bank_doc_05"
+N_SAMPLES = 2
+
+
+def _run_case(out_dir: Path, config_path, overrides: list[str]) -> None:
+    out_dir.mkdir(parents=True, exist_ok=True)
+    config = load_config(config_path=config_path, overrides=overrides)
+    ctx = GeneratorContext(config)
+
+    manifest = {}
+    for i in range(1, N_SAMPLES + 1):
+        meta, final_image, _ = ctx.run_sample(i)
+        Image.fromarray(final_image).save(out_dir / f"case_{i}.png")
+
+        effects = meta["augmentation"]["effects"]
+        applied = [n for n, r in effects.items() if r["applied"]]
+        manifest[f"case_{i}"] = {
+            "applied_effects": applied,
+            "n_applied": len(applied),
+            "n_total": len(effects),
+            "difficulty_score": meta["difficulty"]["score"],
+            "difficulty_tier": meta["difficulty"]["tier"],
+            "placement": {
+                "rotation_deg": meta["placement"]["rotation_deg"],
+                "scale_factor": meta["placement"]["scale_factor"],
+                "misplaced": meta["placement"]["misplaced"],
+            },
+        }
+        print(f"[{out_dir.parent.name}/case_{i}] {len(applied)}/{len(effects)} effects, "
+              f"difficulty={meta['difficulty']['score']:.3f} ({meta['difficulty']['tier']})")
+
+    (out_dir / "case_manifest.json").write_text(json.dumps(manifest, indent=2), encoding="utf-8")
+
+
+def main() -> None:
+    # Normal: configs/generate.yaml's realistic "varied batch" probabilities, unmodified.
+    _run_case(
+        ROOT / "multiple_degradation" / "case_assets",
+        ROOT / "configs" / "generate.yaml",
+        [f"document.template={TEMPLATE_ID}", "generation.run_validation=false"],
+    )
+    # Extreme: every effect pushed high, worst-case placement/rendering.
+    _run_case(
+        ROOT / "multiple_degradation_extreme" / "case_assets",
+        None,
+        extreme_overrides(),
+    )
+    print("\nDone.")
+
+
+if __name__ == "__main__":
+    main()

scripts/generate_degradation_gallery.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python
+"""Generate a labeled sample gallery of every augmentation effect in isolation.
+
+For each of the 25 configurable augmentation families, forces that one effect
+on (probability=1.0) and disables every other effect, so the visual result is
+attributable to that effect alone. Placement is frozen (no rotation/scale/
+misplacement jitter, fixed template) so samples across effects are directly
+comparable. Writes 5 sample images per effect to degradation/<effect>/, each
+a multi-panel figure (full page, signature crop, ink mask, coverage metrics,
+difficulty breakdown) via the existing visualizer.
+
+Usage:
+    python scripts/generate_degradation_gallery.py
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from src.config.loader import load_config
+from src.generator import GeneratorContext
+from src.visualization.visualizer import save_visualization
+
+SIGNATURE_EFFECTS = [
+    "rotation", "stroke_dilation",
+    "ink_fading", "ink_bleed", "motion_blur", "gaussian_blur",
+]
+DOCUMENT_EFFECTS = [
+    "perspective", "contrast", "gamma", "coffee_stain", "stain",
+    "shadow", "crumple", "discoloration", "page_tilt", "dust", "scanner_streaks",
+    "scanner_noise", "salt_pepper", "jpeg_compression",
+]
+ALL_EFFECTS = SIGNATURE_EFFECTS + DOCUMENT_EFFECTS
+
+OUT_ROOT = Path(__file__).resolve().parents[1] / "degradation"
+SAMPLES_PER_EFFECT = 5
+TEMPLATE_ID = "bank_doc_05"  # decent-sized signature box (255x35px)
+FORCED_STRENGTH = 0.75
+
+
+def build_overrides(target_effect: str) -> list[str]:
+    overrides = [
+        f"document.template={TEMPLATE_ID}",
+        "placement.rotation_deg.min=0", "placement.rotation_deg.max=0",
+        "placement.scale_factor.min=0.85", "placement.scale_factor.max=0.85",
+        "placement.x_offset=0", "placement.y_offset=0",
+        "placement.misplacement_probability=0.0",
+        "generation.run_validation=false",
+    ]
+    for name in ALL_EFFECTS:
+        is_target = name == target_effect
+        overrides.append(f"augmentation.{name}.enabled={'true' if is_target else 'false'}")
+        overrides.append(f"augmentation.{name}.probability={'1.0' if is_target else '0.0'}")
+    overrides.append(f"augmentation.{target_effect}.strength={FORCED_STRENGTH}")
+    return overrides
+
+
+def main() -> None:
+    OUT_ROOT.mkdir(parents=True, exist_ok=True)
+    for effect in ALL_EFFECTS:
+        out_dir = OUT_ROOT / effect
+        out_dir.mkdir(parents=True, exist_ok=True)
+
+        config = load_config(overrides=build_overrides(effect))
+        ctx = GeneratorContext(config)
+
+        for i in range(1, SAMPLES_PER_EFFECT + 1):
+            metadata, final_image, _ = ctx.run_sample(i)
+            save_visualization(out_dir / f"sample_{i}.png", final_image, metadata)
+
+        print(f"[{effect}] wrote {SAMPLES_PER_EFFECT} samples -> {out_dir}")
+
+
+if __name__ == "__main__":
+    main()