feat: replace ultralytics/YOLOv8 with Conditional DETR (Apache 2.0)

- core/signature.py: get_yolo() → get_detector() via transformers AutoImageProcessor +
AutoModelForObjectDetection (tech4humans/conditional-detr-50-signature-detector)
- requirements.txt: remove ultralytics>=8.0.0, albumentations>=1.3.0; add timm>=0.9.0
- core/pipeline.py, app/grapholab_demo.py: update UI strings YOLOv8 → Conditional DETR
- notebooks: new 04_signature_detection_detr.ipynb; archive old yolo notebook
- notebooks/01, 03: update references and links to Lab 04

Removes AGPL-3.0 dependency blocking commercial release.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

app/grapholab_demo.py

@@ -414,7 +414,7 @@ with gr.Blocks() as pipeline_tab:
         "Il sistema eseguirà in sequenza tutti e sei gli strumenti AI e produrrà un **referto forense integrato**.\n\n"
         "| Step | Strumento | Input |\n"
         "|------|-----------|-------|\n"
-        "| 1 | Rilevamento Firma (YOLOv8) | Documento |\n"
+        "| 1 | Rilevamento Firma (Conditional DETR) | Documento |\n"
         "| 2 | Trascrizione HTR (EasyOCR) | Documento |\n"
         "| 3 | Riconoscimento Entità — NER | Testo da Step 2 |\n"
         "| 4 | Identificazione Scrittore | Documento |\n"
@@ -430,7 +430,7 @@ with gr.Blocks() as pipeline_tab:
     pipe_btn = gr.Button("▶  Avvia Analisi Forense", variant="primary", size="lg")
 
     with gr.Column(visible=False) as pipe_results:
-        gr.Markdown("### Step 1 — Rilevamento Firma (YOLOv8)")
+        gr.Markdown("### Step 1 — Rilevamento Firma (Conditional DETR)")
         with gr.Row():
             out_s1_img = gr.Image(label="Documento annotato", type="numpy")
             out_s1_txt = gr.Textbox(label="Riepilogo", lines=3)

core/pipeline.py

@@ -304,7 +304,7 @@ def generate_forensic_pdf(results: PipelineResults) -> str:
         pdf.image(buf, x=x, w=disp_w, h=disp_h)
         pdf.ln(4)
 
-    _section_title("Step 1 — Rilevamento Firma (YOLOv8)")
+    _section_title("Step 1 — Rilevamento Firma (Conditional DETR)")
     _body_text(results.sig_detect_summary)
     _embed_image(results.sig_detect_image)
 

core/signature.py

@@ -3,10 +3,10 @@ GraphoLab core — Signature Verification and Detection.
 
 Provides:
   - get_signet()            lazy loader for the SigNet model
-  - get_yolo()              lazy loader for the YOLOv8 signature detector
+  - get_detector()          lazy loader for the Conditional DETR signature detector
   - preprocess_signature()  sigver-compatible preprocessing
   - sig_verify()            verify signature authenticity (SigNet)
-  - sig_detect()            detect signature locations in a document (YOLO)
+  - sig_detect()            detect signature locations in a document (Conditional DETR)
   - detect_and_crop()       detect + return annotated image and first crop
 """
 
@@ -14,7 +14,6 @@ from __future__ import annotations
 
 import io
 import os
-import tempfile
 import threading
 from collections import OrderedDict
 from pathlib import Path
@@ -38,8 +37,7 @@ DEVICE = "cuda" if torch.cuda.is_available() else "cpu"
 SIGNET_CANVAS = (952, 1360)
 SIG_THRESHOLD = 0.35
 
-YOLO_REPO = "tech4humans/yolov8s-signature-detector"
-YOLO_FILENAME = "yolov8s.pt"
+DETR_REPO = "tech4humans/conditional-detr-50-signature-detector"
 
 # ──────────────────────────────────────────────────────────────────────────────
 # SigNet architecture
@@ -95,8 +93,9 @@ _signet = None
 _signet_pretrained = False
 _signet_lock = threading.Lock()
 
-_yolo_model = None
-_yolo_lock = threading.Lock()
+_detector_processor = None
+_detector_model = None
+_detector_lock = threading.Lock()
 
 
 def get_signet(weights_path: Path):
@@ -117,21 +116,17 @@ def get_signet(weights_path: Path):
     return _signet
 
 
-def get_yolo():
-    """Return the YOLO signature detector, downloading on first call (thread-safe)."""
-    global _yolo_model
-    if _yolo_model is None:
-        with _yolo_lock:
-            if _yolo_model is None:
-                from huggingface_hub import hf_hub_download
-                from ultralytics import YOLO
-                print("Loading YOLOv8 signature detector...")
-                hf_token = os.environ.get("HF_TOKEN")
-                model_path = hf_hub_download(
-                    repo_id=YOLO_REPO, filename=YOLO_FILENAME, token=hf_token
-                )
-                _yolo_model = YOLO(model_path)
-    return _yolo_model
+def get_detector():
+    """Return the Conditional DETR signature detector, downloading on first call (thread-safe)."""
+    global _detector_processor, _detector_model
+    if _detector_model is None:
+        with _detector_lock:
+            if _detector_model is None:
+                from transformers import AutoImageProcessor, AutoModelForObjectDetection
+                print("Loading Conditional DETR signature detector...")
+                _detector_processor = AutoImageProcessor.from_pretrained(DETR_REPO)
+                _detector_model = AutoModelForObjectDetection.from_pretrained(DETR_REPO).to(DEVICE).eval()
+    return _detector_processor, _detector_model
 
 
 # ──────────────────────────────────────────────────────────────────────────────
@@ -288,7 +283,7 @@ def sig_detect(
     image: np.ndarray,
     conf_threshold: float,
 ) -> tuple[np.ndarray, str]:
-    """Detect signature locations in a document image using YOLO.
+    """Detect signature locations in a document image using Conditional DETR.
 
     Args:
         image:          RGB numpy array of the document.
@@ -301,46 +296,39 @@ def sig_detect(
     if image is None:
         return image, "Carica un'immagine del documento."
     try:
-        yolo = get_yolo()
+        processor, model = get_detector()
     except Exception as e:
         msg = (
             "⚠️ **Modello non disponibile.**\n\n"
-            "Il modello `tech4humans/yolov8s-signature-detector` è ad accesso limitato su Hugging Face.\n\n"
-            "**Per abilitare questa sezione:**\n"
-            "1. Crea un account su huggingface.co\n"
-            "2. Richiedi l'accesso su huggingface.co/tech4humans/yolov8s-signature-detector\n"
-            "3. Crea un token su huggingface.co/settings/tokens\n"
-            "4. Imposta la variabile d'ambiente `HF_TOKEN=<il_tuo_token>` prima di avviare l'app\n\n"
+            f"Impossibile caricare `{DETR_REPO}`.\n\n"
             f"Errore: {e}"
         )
         return image, msg
 
     pil_img = Image.fromarray(image).convert("RGB")
-    with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as tmp:
-        pil_img.save(tmp.name)
-        tmp_path = tmp.name
-
-    results = yolo.predict(tmp_path, conf=conf_threshold, verbose=False)
-    os.unlink(tmp_path)
+    inputs = processor(images=pil_img, return_tensors="pt").to(DEVICE)
+    with torch.no_grad():
+        outputs = model(**inputs)
+    target_sizes = torch.tensor([pil_img.size[::-1]])
+    results = processor.post_process_object_detection(
+        outputs, threshold=conf_threshold, target_sizes=target_sizes
+    )[0]
 
-    result = results[0]
     annotated = image.copy()
     count = 0
-
-    if result.boxes is not None:
-        for box in result.boxes:
-            x1, y1, x2, y2 = box.xyxy[0].cpu().numpy().astype(int)
-            conf = float(box.conf[0].cpu())
-            cv2.rectangle(annotated, (x1, y1), (x2, y2), (255, 0, 0), 2)
-            cv2.putText(annotated, f"Sig #{count+1}  {conf:.0%}",
-                        (x1, max(y1 - 8, 0)),
-                        cv2.FONT_HERSHEY_SIMPLEX, 0.6, (255, 0, 0), 2)
-            count += 1
+    for score, box in zip(results["scores"], results["boxes"]):
+        x1, y1, x2, y2 = box.cpu().numpy().astype(int)
+        conf = float(score.cpu())
+        cv2.rectangle(annotated, (x1, y1), (x2, y2), (255, 0, 0), 2)
+        cv2.putText(annotated, f"Sig #{count+1}  {conf:.0%}",
+                    (x1, max(y1 - 8, 0)),
+                    cv2.FONT_HERSHEY_SIMPLEX, 0.6, (255, 0, 0), 2)
+        count += 1
 
     summary = (
         f"Rilevat{'a' if count == 1 else 'e'} {count} firma{'' if count == 1 else 'e'} "
         f"(confidenza ≥ {conf_threshold:.0%})\n\n"
-        f"**Modello:** `tech4humans/yolov8s-signature-detector`\n"
+        f"**Modello:** `{DETR_REPO}`\n"
         f"**Uso forense:** Estrazione automatica di firme da documenti legali."
     )
     return annotated, summary
@@ -350,42 +338,41 @@ def detect_and_crop(
     image: np.ndarray,
     conf_threshold: float = 0.3,
 ) -> tuple[np.ndarray, np.ndarray | None, str]:
-    """Run YOLO detection and return (annotated, first_crop, summary).
+    """Run Conditional DETR detection and return (annotated, first_crop, summary).
 
-    Gracefully degrades when YOLO is not available (missing HF_TOKEN).
+    Gracefully degrades when the model is not available.
     """
     annotated = image.copy()
     try:
-        yolo = get_yolo()
+        processor, model = get_detector()
     except Exception:
-        return annotated, None, "⚠️ Rilevamento firma non disponibile (HF_TOKEN mancante)."
+        return annotated, None, "⚠️ Rilevamento firma non disponibile."
 
     pil_img = Image.fromarray(image).convert("RGB")
-    with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as tmp:
-        pil_img.save(tmp.name)
-        tmp_path = tmp.name
-
-    results = yolo.predict(tmp_path, conf=conf_threshold, verbose=False)
-    os.unlink(tmp_path)
+    inputs = processor(images=pil_img, return_tensors="pt").to(DEVICE)
+    with torch.no_grad():
+        outputs = model(**inputs)
+    target_sizes = torch.tensor([pil_img.size[::-1]])
+    results = processor.post_process_object_detection(
+        outputs, threshold=conf_threshold, target_sizes=target_sizes
+    )[0]
 
-    result = results[0]
     first_crop: np.ndarray | None = None
     count = 0
 
-    if result.boxes is not None:
-        for box in result.boxes:
-            x1, y1, x2, y2 = box.xyxy[0].cpu().numpy().astype(int)
-            conf = float(box.conf[0].cpu())
-            cv2.rectangle(annotated, (x1, y1), (x2, y2), (255, 0, 0), 2)
-            cv2.putText(annotated, f"Sig #{count+1}  {conf:.0%}",
-                        (x1, max(y1 - 8, 0)),
-                        cv2.FONT_HERSHEY_SIMPLEX, 0.6, (255, 0, 0), 2)
-            if count == 0:
-                x1c = max(0, x1); y1c = max(0, y1)
-                x2c = min(image.shape[1], x2); y2c = min(image.shape[0], y2)
-                if x2c > x1c and y2c > y1c:
-                    first_crop = image[y1c:y2c, x1c:x2c]
-            count += 1
+    for score, box in zip(results["scores"], results["boxes"]):
+        x1, y1, x2, y2 = box.cpu().numpy().astype(int)
+        conf = float(score.cpu())
+        cv2.rectangle(annotated, (x1, y1), (x2, y2), (255, 0, 0), 2)
+        cv2.putText(annotated, f"Sig #{count+1}  {conf:.0%}",
+                    (x1, max(y1 - 8, 0)),
+                    cv2.FONT_HERSHEY_SIMPLEX, 0.6, (255, 0, 0), 2)
+        if count == 0:
+            x1c = max(0, x1); y1c = max(0, y1)
+            x2c = min(image.shape[1], x2); y2c = min(image.shape[0], y2)
+            if x2c > x1c and y2c > y1c:
+                first_crop = image[y1c:y2c, x1c:x2c]
+        count += 1
 
     summary = (
         f"Rilevat{'a' if count == 1 else 'e'} {count} firma{'' if count == 1 else 'e'}."

notebooks/01_intro_forensic_graphology.ipynb

@@ -83,55 +83,7 @@
   {
    "cell_type": "markdown",
    "metadata": {},
-   "source": [
-    "## Overview of the GraphoLab Labs\n",
-    "\n",
-    "| Lab | Title | AI Technique | Key Libraries |\n",
-    "|-----|-------|-------------|---------------|\n",
-    "| 02 | Handwritten Text Recognition | TrOCR (Transformer) | `transformers`, `torch` |\n",
-    "| 03 | Signature Verification | Siamese Neural Network | `torch`, `torchvision` |\n",
-    "| 04 | Signature Detection | YOLOv8 Object Detection | `ultralytics` |\n",
-    "| 05 | Writer Identification | CNN Features + Classifier | `torch`, `scikit-learn` |\n",
-    "| 06 | Graphological Analysis | OpenCV + Image Processing | `opencv-python`, `matplotlib` |\n",
-    "\n",
-    "---\n",
-    "\n",
-    "## Key Concepts\n",
-    "\n",
-    "### Handwritten Text Recognition (HTR)\n",
-    "HTR converts handwriting images into machine-readable text. Modern approaches use **sequence-to-sequence Transformers** (like TrOCR) that encode the image with a Vision Transformer and decode it token-by-token with a language model.\n",
-    "\n",
-    "### Signature Verification\n",
-    "A **Siamese network** takes two images and learns whether they are from the same class (genuine vs. forged). It does this by mapping both images into an embedding space and measuring their distance — close = same author, far = different/forged.\n",
-    "\n",
-    "### Writer Identification\n",
-    "Like fingerprints, handwriting has unique style characteristics. A classifier trained on enough samples can distinguish between writers even on short text fragments.\n",
-    "\n",
-    "### Graphological Feature Extraction\n",
-    "Classical computer vision (OpenCV) can objectively measure graphological traits:\n",
-    "- **Slant**: angle of letter strokes relative to vertical\n",
-    "- **Pressure**: mean pixel intensity in stroke regions\n",
-    "- **Spacing**: distribution of whitespace between words and letters\n",
-    "- **Size**: height/width statistics of letter forms\n",
-    "\n",
-    "---\n",
-    "\n",
-    "## Legal and Ethical Notes\n",
-    "\n",
-    "- AI-generated analysis must be reviewed and validated by a qualified forensic document examiner before use in court.\n",
-    "- Model outputs are probabilistic and carry uncertainty — always report confidence scores alongside verdicts.\n",
-    "- Training data biases can affect performance on under-represented handwriting styles, ages, or languages.\n",
-    "- These tools are for **augmenting** expert analysis, not replacing it.\n",
-    "\n",
-    "---\n",
-    "\n",
-    "## References\n",
-    "\n",
-    "- Li, M. et al. (2021). *TrOCR: Transformer-based Optical Character Recognition with Pre-trained Models.* arXiv:2109.10282\n",
-    "- Dey, S. et al. (2017). *SigNet: Convolutional Siamese Network for Writer Independent Offline Signature Verification.* arXiv:1707.02131\n",
-    "- Hafemann, L. G. et al. (2017). *Learning Features for Offline Handwritten Signature Verification using Deep Convolutional Neural Networks.* Pattern Recognition.\n",
-    "- Marti, U.-V. & Bunke, H. (2002). *The IAM-database: an English sentence database for offline handwriting recognition.* IJDAR.\n"
-   ]
+   "source": "## Overview of the GraphoLab Labs\n\n| Lab | Title | AI Technique | Key Libraries |\n|-----|-------|-------------|---------------|\n| 02 | Handwritten Text Recognition | TrOCR (Transformer) | `transformers`, `torch` |\n| 03 | Signature Verification | Siamese Neural Network | `torch`, `torchvision` |\n| 04 | Signature Detection | Conditional DETR (Transformer) | `transformers` |\n| 05 | Writer Identification | CNN Features + Classifier | `torch`, `scikit-learn` |\n| 06 | Graphological Analysis | OpenCV + Image Processing | `opencv-python`, `matplotlib` |\n\n---\n\n## Key Concepts\n\n### Handwritten Text Recognition (HTR)\nHTR converts handwriting images into machine-readable text. Modern approaches use **sequence-to-sequence Transformers** (like TrOCR) that encode the image with a Vision Transformer and decode it token-by-token with a language model.\n\n### Signature Verification\nA **Siamese network** takes two images and learns whether they are from the same class (genuine vs. forged). It does this by mapping both images into an embedding space and measuring their distance — close = same author, far = different/forged.\n\n### Writer Identification\nLike fingerprints, handwriting has unique style characteristics. A classifier trained on enough samples can distinguish between writers even on short text fragments.\n\n### Graphological Feature Extraction\nClassical computer vision (OpenCV) can objectively measure graphological traits:\n- **Slant**: angle of letter strokes relative to vertical\n- **Pressure**: mean pixel intensity in stroke regions\n- **Spacing**: distribution of whitespace between words and letters\n- **Size**: height/width statistics of letter forms\n\n---\n\n## Legal and Ethical Notes\n\n- AI-generated analysis must be reviewed and validated by a qualified forensic document examiner before use in court.\n- Model outputs are probabilistic and carry uncertainty — always report confidence scores alongside verdicts.\n- Training data biases can affect performance on under-represented handwriting styles, ages, or languages.\n- These tools are for **augmenting** expert analysis, not replacing it.\n\n---\n\n## References\n\n- Li, M. et al. (2021). *TrOCR: Transformer-based Optical Character Recognition with Pre-trained Models.* arXiv:2109.10282\n- Dey, S. et al. (2017). *SigNet: Convolutional Siamese Network for Writer Independent Offline Signature Verification.* arXiv:1707.02131\n- Hafemann, L. G. et al. (2017). *Learning Features for Offline Handwritten Signature Verification using Deep Convolutional Neural Networks.* Pattern Recognition.\n- Marti, U.-V. & Bunke, H. (2002). *The IAM-database: an English sentence database for offline handwriting recognition.* IJDAR.\n- Meng, D. et al. (2021). *Conditional DETR for Fast Training Convergence.* ICCV 2021."
   }
  ],
  "metadata": {
@@ -147,4 +99,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}

notebooks/03_signature_verification_siamese.ipynb

@@ -494,19 +494,7 @@
    "cell_type": "markdown",
    "id": "fe74b3d8",
    "metadata": {},
-   "source": [
-    "## Forensic Notes\n",
-    "\n",
-    "- **Threshold calibration:** The default threshold of 0.70 is a starting point. Calibrate it on a representative dataset of genuine and forged pairs for your specific use case.\n",
-    "- **Multiple reference samples:** Always compare against several genuine reference signatures (minimum 5–10), not just one.\n",
-    "- **Model limitations:** ResNet-18 ImageNet features are a general-purpose baseline. For production forensic use, domain-specific SigNet weights (trained on CEDAR or SigComp'11) provide significantly better performance — see [luizgh/sigver](https://github.com/luizgh/sigver).\n",
-    "- **Scan quality:** Use high-resolution scans (≥300 DPI) with consistent lighting and background.\n",
-    "- **AI is a screening tool:** A high similarity score supports — but does not prove — authenticity. Skilled forgeries may score high; unusual genuine signatures may score low.\n",
-    "\n",
-    "---\n",
-    "\n",
-    "**Next lab →** [04 — Signature Detection in Documents (YOLOv8)](04_signature_detection_yolo.ipynb)\n"
-   ]
+   "source": "## Forensic Notes\n\n- **Threshold calibration:** The default threshold of 0.70 is a starting point. Calibrate it on a representative dataset of genuine and forged pairs for your specific use case.\n- **Multiple reference samples:** Always compare against several genuine reference signatures (minimum 5–10), not just one.\n- **Model limitations:** ResNet-18 ImageNet features are a general-purpose baseline. For production forensic use, domain-specific SigNet weights (trained on CEDAR or SigComp'11) provide significantly better performance — see [luizgh/sigver](https://github.com/luizgh/sigver).\n- **Scan quality:** Use high-resolution scans (≥300 DPI) with consistent lighting and background.\n- **AI is a screening tool:** A high similarity score supports — but does not prove — authenticity. Skilled forgeries may score high; unusual genuine signatures may score low.\n\n---\n\n**Next lab →** [04 — Signature Detection in Documents (Conditional DETR)](04_signature_detection_detr.ipynb)"
   }
  ],
  "metadata": {
@@ -530,4 +518,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}

notebooks/04_signature_detection_detr.ipynb

@@ -0,0 +1,384 @@
+{
+ "nbformat": 4,
+ "nbformat_minor": 5,
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.11.0"
+  }
+ },
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "a1b2c3d4",
+   "metadata": {},
+   "source": [
+    "# Lab 04 — Signature Detection in Documents (Conditional DETR)\n",
+    "\n",
+    "> **GraphoLab** | Forensic Graphology Laboratory\n",
+    "\n",
+    "**Model:** `tech4humans/conditional-detr-50-signature-detector` (Hugging Face / Apache 2.0)  \n",
+    "**Task:** Locate and extract signatures from scanned documents  \n",
+    "**Forensic use case:** Document pipeline — detect → extract → verify (feeds into Lab 03)\n",
+    "\n",
+    "---\n",
+    "\n",
+    "## How Conditional DETR Object Detection Works\n",
+    "\n",
+    "DETR (DEtection TRansformer) reformulates object detection as a set-prediction problem using a Transformer encoder-decoder:\n",
+    "\n",
+    "1. A **CNN backbone** (ResNet-50) extracts spatial feature maps from the image.\n",
+    "2. The **Transformer encoder** refines the feature maps with self-attention.\n",
+    "3. A fixed set of learned **object queries** are decoded by the Transformer decoder — each query \"attends\" to the relevant image region.\n",
+    "4. A feed-forward network predicts a bounding box and class label for each query.\n",
+    "\n",
+    "**Conditional DETR** (Meng et al., 2021) speeds up convergence vs. original DETR by conditioning cross-attention on predicted reference points, reducing the number of training epochs needed by ~10×.\n",
+    "\n",
+    "The model was fine-tuned on annotated signature images to detect signatures specifically in document scans, achieving **mAP@50 = 93.65%**.\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b2c3d4e5",
+   "metadata": {},
+   "source": [
+    "## GraphoLab Core — Quick Start\n",
+    "\n",
+    "> The production implementation of signature detection is available in [`core/signature.py`](../core/signature.py).\n",
+    "> It wraps **Conditional DETR** (`tech4humans/conditional-detr-50-signature-detector`) with lazy thread-safe model loading,\n",
+    "> bounding-box annotation, and automatic cropping of detected signatures.\n",
+    ">\n",
+    "> Run the cell below to import it directly. The remaining cells implement the same detection\n",
+    "> pipeline from scratch for educational purposes."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "c3d4e5f6",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# GraphoLab Core — production usage\n",
+    "# Run this cell to use the shared core module instead of the notebook implementation below.\n",
+    "import sys, pathlib\n",
+    "sys.path.insert(0, str(pathlib.Path(\"..\").resolve()))\n",
+    "\n",
+    "from core.signature import detect_and_crop, sig_detect, get_detector\n",
+    "from PIL import Image\n",
+    "import numpy as np\n",
+    "\n",
+    "# Example: detect and crop signature from a document\n",
+    "# doc = np.array(Image.open(\"../data/samples/document_with_signature_01.png\").convert(\"RGB\"))\n",
+    "# annotated, crop, summary = detect_and_crop(doc)\n",
+    "# print(summary)\n",
+    "print(\"core.signature imported — detect_and_crop(), sig_detect() ready.\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d4e5f6a7",
+   "metadata": {},
+   "source": [
+    "## Setup\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "e5f6a7b8",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# !pip install transformers torch Pillow matplotlib opencv-python"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "f6a7b8c9",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import warnings\n",
+    "warnings.filterwarnings('ignore')\n",
+    "\n",
+    "from pathlib import Path\n",
+    "\n",
+    "import cv2\n",
+    "import numpy as np\n",
+    "import torch\n",
+    "from PIL import Image\n",
+    "import matplotlib.pyplot as plt\n",
+    "import matplotlib.patches as patches\n",
+    "\n",
+    "from transformers import AutoImageProcessor, AutoModelForObjectDetection\n",
+    "\n",
+    "DEVICE = \"cuda\" if torch.cuda.is_available() else \"cpu\"\n",
+    "print(f\"Libraries loaded. Device: {DEVICE}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a7b8c9d0",
+   "metadata": {},
+   "source": [
+    "## Load the Model\n",
+    "\n",
+    "The model is downloaded from Hugging Face the first time and cached locally (~170 MB).  \n",
+    "No token or access request required — Apache 2.0 licence, publicly available.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b8c9d0e1",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "DETR_REPO = \"tech4humans/conditional-detr-50-signature-detector\"\n",
+    "\n",
+    "print(\"Loading Conditional DETR signature detector from Hugging Face...\")\n",
+    "processor = AutoImageProcessor.from_pretrained(DETR_REPO)\n",
+    "model = AutoModelForObjectDetection.from_pretrained(DETR_REPO).to(DEVICE).eval()\n",
+    "print(\"Model ready.\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c9d0e1f2",
+   "metadata": {},
+   "source": [
+    "## Helper Functions\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d0e1f2a3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def detect_signatures(image: Image.Image | Path | str, conf_threshold: float = 0.3) -> dict:\n",
+    "    \"\"\"Run signature detection on a PIL image or image path.\"\"\"\n",
+    "    if not isinstance(image, Image.Image):\n",
+    "        image = Image.open(image).convert(\"RGB\")\n",
+    "    else:\n",
+    "        image = image.convert(\"RGB\")\n",
+    "\n",
+    "    inputs = processor(images=image, return_tensors=\"pt\").to(DEVICE)\n",
+    "    with torch.no_grad():\n",
+    "        outputs = model(**inputs)\n",
+    "\n",
+    "    target_sizes = torch.tensor([image.size[::-1]])\n",
+    "    results = processor.post_process_object_detection(\n",
+    "        outputs, threshold=conf_threshold, target_sizes=target_sizes\n",
+    "    )[0]\n",
+    "\n",
+    "    detections = []\n",
+    "    for score, box in zip(results[\"scores\"], results[\"boxes\"]):\n",
+    "        x1, y1, x2, y2 = box.cpu().numpy().astype(int)\n",
+    "        detections.append({\n",
+    "            \"bbox\": (x1, y1, x2, y2),\n",
+    "            \"confidence\": float(score.cpu()),\n",
+    "        })\n",
+    "\n",
+    "    return {\n",
+    "        \"image\": image,\n",
+    "        \"detections\": detections,\n",
+    "        \"count\": len(detections),\n",
+    "    }\n",
+    "\n",
+    "\n",
+    "def show_detections(result: dict, title: str = \"Signature Detection\") -> None:\n",
+    "    \"\"\"Visualise detected signatures with bounding boxes.\"\"\"\n",
+    "    image = result[\"image\"]\n",
+    "    detections = result[\"detections\"]\n",
+    "\n",
+    "    fig, ax = plt.subplots(figsize=(12, 8))\n",
+    "    ax.imshow(image)\n",
+    "\n",
+    "    for i, det in enumerate(detections):\n",
+    "        x1, y1, x2, y2 = det[\"bbox\"]\n",
+    "        conf = det[\"confidence\"]\n",
+    "        rect = patches.Rectangle(\n",
+    "            (x1, y1), x2 - x1, y2 - y1,\n",
+    "            linewidth=2, edgecolor='red', facecolor='none'\n",
+    "        )\n",
+    "        ax.add_patch(rect)\n",
+    "        ax.text(x1, y1 - 6, f\"Signature #{i+1}  {conf:.0%}\",\n",
+    "                color='red', fontsize=9, fontweight='bold',\n",
+    "                bbox=dict(facecolor='white', alpha=0.6, pad=1))\n",
+    "\n",
+    "    ax.set_title(f\"{title} — {len(detections)} signature(s) found\", fontsize=13)\n",
+    "    ax.axis('off')\n",
+    "    plt.tight_layout()\n",
+    "    plt.show()\n",
+    "\n",
+    "\n",
+    "def crop_signatures(result: dict, output_dir: Path) -> list:\n",
+    "    \"\"\"Crop and save each detected signature as a separate image file.\"\"\"\n",
+    "    output_dir = Path(output_dir)\n",
+    "    output_dir.mkdir(parents=True, exist_ok=True)\n",
+    "    image = result[\"image\"]\n",
+    "    saved = []\n",
+    "    for i, det in enumerate(result[\"detections\"]):\n",
+    "        x1, y1, x2, y2 = det[\"bbox\"]\n",
+    "        crop = image.crop((x1, y1, x2, y2))\n",
+    "        out_path = output_dir / f\"detected_signature_{i+1:02d}.png\"\n",
+    "        crop.save(out_path)\n",
+    "        saved.append(out_path)\n",
+    "        print(f\"  Saved: {out_path}\")\n",
+    "    return saved"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e1f2a3b4",
+   "metadata": {},
+   "source": [
+    "## Demo 1 — Detect Signatures in a Sample Document\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "f2a3b4c5",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def make_synthetic_document() -> Path:\n",
+    "    \"\"\"Create a simple synthetic document image with a fake signature for demo.\"\"\"\n",
+    "    from PIL import ImageDraw\n",
+    "    img = Image.new('RGB', (800, 1000), color='white')\n",
+    "    draw = ImageDraw.Draw(img)\n",
+    "\n",
+    "    # Simulate document text lines\n",
+    "    for y in range(60, 700, 35):\n",
+    "        line_width = np.random.randint(300, 700)\n",
+    "        draw.rectangle([(60, y), (60 + line_width, y + 10)], fill='#cccccc')\n",
+    "\n",
+    "    # Signature area label\n",
+    "    draw.text((60, 750), \"Signature:\", fill='black')\n",
+    "    # Simulate a cursive signature stroke\n",
+    "    points = [(200, 800), (220, 780), (260, 820), (300, 790),\n",
+    "              (340, 810), (380, 780), (400, 805)]\n",
+    "    draw.line(points, fill='black', width=3)\n",
+    "    draw.line([(200, 830), (420, 830)], fill='black', width=1)\n",
+    "\n",
+    "    out = Path(\"../data/samples/document_with_signature_demo.png\")\n",
+    "    out.parent.mkdir(parents=True, exist_ok=True)\n",
+    "    img.save(out)\n",
+    "    return out\n",
+    "\n",
+    "\n",
+    "samples_dir = Path(\"../data/samples\")\n",
+    "real_doc = samples_dir / \"document_with_signature_01.png\"\n",
+    "\n",
+    "if real_doc.exists():\n",
+    "    doc_path = real_doc\n",
+    "    print(f\"Using real document: {doc_path}\")\n",
+    "else:\n",
+    "    doc_path = make_synthetic_document()\n",
+    "    print(f\"Using synthetic document: {doc_path}\")\n",
+    "\n",
+    "result = detect_signatures(doc_path, conf_threshold=0.25)\n",
+    "print(f\"\\nDetected {result['count']} signature(s)\")\n",
+    "show_detections(result)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a3b4c5d6",
+   "metadata": {},
+   "source": [
+    "## Demo 2 — Crop Detected Signatures for Further Analysis\n",
+    "\n",
+    "The cropped signatures can be fed directly into Lab 03 (Signature Verification):\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b4c5d6e7",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "crops_dir = Path(\"../data/samples/detected_crops\")\n",
+    "\n",
+    "if result[\"count\"] > 0:\n",
+    "    saved_paths = crop_signatures(result, crops_dir)\n",
+    "\n",
+    "    # Show crops\n",
+    "    fig, axes = plt.subplots(1, len(saved_paths), figsize=(4 * len(saved_paths), 3))\n",
+    "    if len(saved_paths) == 1:\n",
+    "        axes = [axes]\n",
+    "    for ax, path in zip(axes, saved_paths):\n",
+    "        ax.imshow(Image.open(path))\n",
+    "        ax.set_title(path.name, fontsize=9)\n",
+    "        ax.axis('off')\n",
+    "    plt.suptitle(\"Extracted Signature Crops\", fontsize=12, fontweight='bold')\n",
+    "    plt.tight_layout()\n",
+    "    plt.show()\n",
+    "    print(f\"\\n{len(saved_paths)} signature(s) saved to {crops_dir}\")\n",
+    "    print(\"These can be used as input for Lab 03 (Signature Verification).\")\n",
+    "else:\n",
+    "    print(\"No signatures detected — nothing to crop.\")\n",
+    "    print(\"Try lowering conf_threshold or using a document with visible signatures.\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c5d6e7f8",
+   "metadata": {},
+   "source": [
+    "## Demo 3 — Load Your Own Document\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d6e7f8a9",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# ─── Change this path to your own scanned document ────────────────────────────\n",
+    "USER_DOC_PATH = \"../data/samples/document_with_signature_01.png\"\n",
+    "CONF_THRESHOLD = 0.30\n",
+    "# ──────────────────────────────────────────────────────────────────────────────\n",
+    "\n",
+    "path = Path(USER_DOC_PATH)\n",
+    "if path.exists():\n",
+    "    res = detect_signatures(path, conf_threshold=CONF_THRESHOLD)\n",
+    "    print(f\"Detected {res['count']} signature(s)\")\n",
+    "    show_detections(res, title=path.name)\n",
+    "else:\n",
+    "    print(f\"File not found: {path}\")\n",
+    "    print(\"Place a scanned document image at the path above and re-run.\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e7f8a9b0",
+   "metadata": {},
+   "source": [
+    "## Forensic Notes\n",
+    "\n",
+    "- Adjust **`conf_threshold`** based on your document quality. Low-resolution scans may need a lower threshold.\n",
+    "- For multi-page PDFs, convert each page to an image first (e.g., with `pdf2image` / `poppler`).\n",
+    "- Detected regions should be **reviewed by a human** before proceeding to automated verification — the detector may occasionally flag stamps, logos, or printed signatures.\n",
+    "- Detection output (coordinates, confidence scores) should be logged and preserved as part of the forensic record.\n",
+    "- Conditional DETR does **not** require Non-Maximum Suppression post-processing — each object query produces at most one prediction, eliminating duplicate detections by design.\n",
+    "\n",
+    "---\n",
+    "\n",
+    "**Next lab →** [05 — Writer Identification](05_writer_identification.ipynb)\n"
+   ]
+  }
+ ]
+}

notebooks/{04_signature_detection_yolo.ipynb → archive/04_signature_detection_yolo.ipynb}

@@ -2,6 +2,7 @@
  "cells": [
   {
    "cell_type": "markdown",
+   "id": "9e1e6c7c",
    "metadata": {},
    "source": [
     "# Lab 04 — Signature Detection in Documents (YOLOv8)\n",
@@ -27,19 +28,44 @@
   {
    "cell_type": "markdown",
    "id": "48jzghnekwn",
-   "source": "## GraphoLab Core — Quick Start\n\n> The production implementation of signature detection is available in [`core/signature.py`](../core/signature.py).\n> It wraps **YOLOv8** (`tech4humans/yolov8s-signature-detector`) with lazy thread-safe model loading,\n> bounding-box annotation, and automatic cropping of detected signatures.\n>\n> Run the cell below to import it directly. The remaining cells implement the same detection\n> pipeline from scratch for educational purposes.",
-   "metadata": {}
+   "metadata": {},
+   "source": [
+    "## GraphoLab Core — Quick Start\n",
+    "\n",
+    "> The production implementation of signature detection is available in [`core/signature.py`](../core/signature.py).\n",
+    "> It wraps **YOLOv8** (`tech4humans/yolov8s-signature-detector`) with lazy thread-safe model loading,\n",
+    "> bounding-box annotation, and automatic cropping of detected signatures.\n",
+    ">\n",
+    "> Run the cell below to import it directly. The remaining cells implement the same detection\n",
+    "> pipeline from scratch for educational purposes."
+   ]
   },
   {
    "cell_type": "code",
+   "execution_count": null,
    "id": "yjec2b865cc",
-   "source": "# GraphoLab Core — production usage\n# Run this cell to use the shared core module instead of the notebook implementation below.\nimport sys, pathlib\nsys.path.insert(0, str(pathlib.Path(\"..\").resolve()))\n\nfrom core.signature import detect_and_crop, sig_detect, get_yolo\nfrom PIL import Image\nimport numpy as np\n\n# Example: detect and crop signature from a document\n# doc = np.array(Image.open(\"../data/samples/document_with_signature_01.png\").convert(\"RGB\"))\n# annotated, crop, summary = detect_and_crop(doc)\n# print(summary)\nprint(\"core.signature imported — detect_and_crop(), sig_detect() ready.\")",
    "metadata": {},
-   "execution_count": null,
-   "outputs": []
+   "outputs": [],
+   "source": [
+    "# GraphoLab Core — production usage\n",
+    "# Run this cell to use the shared core module instead of the notebook implementation below.\n",
+    "import sys, pathlib\n",
+    "sys.path.insert(0, str(pathlib.Path(\"..\").resolve()))\n",
+    "\n",
+    "from core.signature import detect_and_crop, sig_detect, get_yolo\n",
+    "from PIL import Image\n",
+    "import numpy as np\n",
+    "\n",
+    "# Example: detect and crop signature from a document\n",
+    "# doc = np.array(Image.open(\"../data/samples/document_with_signature_01.png\").convert(\"RGB\"))\n",
+    "# annotated, crop, summary = detect_and_crop(doc)\n",
+    "# print(summary)\n",
+    "print(\"core.signature imported — detect_and_crop(), sig_detect() ready.\")"
+   ]
   },
   {
    "cell_type": "markdown",
+   "id": "d04f2c7a",
    "metadata": {},
    "source": [
     "## Setup\n"
@@ -48,6 +74,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
+   "id": "919826d2",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -57,6 +84,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
+   "id": "eca98486",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -79,6 +107,7 @@
   },
   {
    "cell_type": "markdown",
+   "id": "3f9379fa",
    "metadata": {},
    "source": [
     "## Load the Model\n",
@@ -89,6 +118,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
+   "id": "fa0c4ee9",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -105,6 +135,7 @@
   },
   {
    "cell_type": "markdown",
+   "id": "83306ace",
    "metadata": {},
    "source": [
     "## Helper Functions\n"
@@ -113,6 +144,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
+   "id": "80769d03",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -181,6 +213,7 @@
   },
   {
    "cell_type": "markdown",
+   "id": "6eb37bdd",
    "metadata": {},
    "source": [
     "## Demo 1 — Detect Signatures in a Sample Document\n"
@@ -189,6 +222,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
+   "id": "e4a7bc76",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -234,6 +268,7 @@
   },
   {
    "cell_type": "markdown",
+   "id": "d41087e5",
    "metadata": {},
    "source": [
     "## Demo 2 — Crop Detected Signatures for Further Analysis\n",
@@ -244,6 +279,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
+   "id": "b5170d57",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -272,6 +308,7 @@
   },
   {
    "cell_type": "markdown",
+   "id": "e16a15d9",
    "metadata": {},
    "source": [
     "## Demo 3 — Load Your Own Document\n"
@@ -280,6 +317,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
+   "id": "24edb2bf",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -300,6 +338,7 @@
   },
   {
    "cell_type": "markdown",
+   "id": "c2183d23",
    "metadata": {},
    "source": [
     "## Forensic Notes\n",
@@ -317,15 +356,23 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
   "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
    "name": "python",
-   "version": "3.11.0"
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.9"
   }
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}

requirements.txt

@@ -8,14 +8,12 @@ torchvision>=0.16.0
 # Hugging Face ecosystem
 transformers>=4.35.0
 huggingface_hub>=0.25.1
+timm>=0.9.0
 
 # Computer Vision
 Pillow>=10.0.0
 opencv-python>=4.8.0
 
-# Object Detection (YOLOv8)
-ultralytics>=8.0.0
-
 # audioop backport for Python 3.13 (pydub dependency of gradio 4.x)
 audioop-lts; python_version >= "3.13"
 fpdf2>=2.7          # PDF report generation
@@ -30,9 +28,6 @@ scipy>=1.11.0
 jupyterlab>=4.0.0
 ipywidgets>=8.0.0
 
-# Image augmentation (used in signature processing)
-albumentations>=1.3.0
-
 # Signature preprocessing (sigver-compatible)
 scikit-image>=0.21.0