archival-index-card-detector

Archival Index Card Detector

Superseded by NationalLibraryOfScotland/card-detector-retinanet, a newer detector trained on the same collection.

A YOLO26n model trained to detect index cards in digitized archival document scans.

Model Description

This model detects index cards in scanned archival documents, returning bounding box coordinates for each detected card. It was trained specifically on historical library index cards from the National Library of Scotland's Advocates Library collection.

Single class: index_card

Performance

Trained on 905 images over 85 epochs.

How It Was Made

This model was built through an iterative loop using Claude Code to build tooling and UV scripts on HF Jobs for inference.

The Iterative Process

Step by Step

1. Zero-shot bootstrap with SAM3: Ran SAM3 via a UV script on HF Jobs to get initial bounding box predictions on ~100 archival images. Result: only 31% true positive rate (many false positives on backs of cards).

2. Claude Code built annotation tooling: Asked Claude Code to build an HTML bounding box editor for correcting the SAM3 outputs. It created a simple tool to visualize images, adjust boxes, and export corrected annotations.

3. Manual correction: Used the bbox editor to correct annotations - removing false positives from versos (card backs) and adjusting box coordinates.

4. Train v1: Fine-tuned YOLO26n on the corrected 100 images → 94.4% mAP@50-95.

5. Expand with model predictions: Claude Code built scripts to run the trained model on new images from HF Hub, outputting predictions in the same format as SAM3 for the bbox editor.

6. Correct and retrain: Loaded model predictions into the editor, corrected errors, merged with existing annotations, retrained → v2 (95.5%) → v3 (99.2%).

The Pattern

AI bootstraps → Claude builds tooling → human corrects → model improves → repeat

This workflow is useful when you have domain-specific detection needs but no labelled training data. The key insight: use AI (SAM3/previous model) to generate candidate annotations, then spend human time correcting rather than creating from scratch.

Usage

from ultralytics import YOLO
from huggingface_hub import hf_hub_download

# Download and load model
model = YOLO(hf_hub_download(
    repo_id="NationalLibraryOfScotland/archival-index-card-detector",
    filename="model.pt"
))

# Run inference
results = model.predict("scan.jpg")

# Get bounding boxes
for result in results:
    boxes = result.boxes
    for box in boxes:
        x1, y1, x2, y2 = box.xyxy[0].tolist()
        confidence = box.conf[0].item()
        print(f"Index card detected at ({x1:.0f}, {y1:.0f}, {x2:.0f}, {y2:.0f}) with confidence {confidence:.2f}")

Cropping detected cards

from ultralytics import YOLO
from PIL import Image

model = YOLO(hf_hub_download(
    repo_id="NationalLibraryOfScotland/archival-index-card-detector",
    filename="model.pt"
))
image = Image.open("scan.jpg")
results = model.predict(image)

for i, box in enumerate(results[0].boxes):
    x1, y1, x2, y2 = box.xyxy[0].tolist()
    # Add padding (10%)
    w, h = x2 - x1, y2 - y1
    pad = 0.1
    x1 = max(0, x1 - w * pad)
    y1 = max(0, y1 - h * pad)
    x2 = min(image.width, x2 + w * pad)
    y2 = min(image.height, y2 + h * pad)

    cropped = image.crop((x1, y1, x2, y2))
    cropped.save(f"card_{i}.jpg")

Limitations

• Specific card style: Trained on NLS Advocates Library index cards (typed, early-mid 20th century). May need fine-tuning for different card formats, handwritten cards, or cards from other collections
• Scan quality: Best results on high-quality scans; may struggle with very low resolution or heavily degraded images
• Single class: Only detects "index card" - does not distinguish between different card types or sections within cards

Training Details

• Base model: YOLO26n (ultralytics)
• Training images: 905 (including ~50% negative examples)
• Epochs: 85
• Hardware: Apple M1 Pro (MPS)
• Framework: ultralytics
• Development: Claude Code for tooling and scripts
• Initial labels: SAM3 UV script on HF Jobs

Use Cases

• Automatically locating index cards in digitised card catalogue collections
• Pre-processing step for OCR or metadata extraction pipelines
• Quality control for digitisation projects (detecting missed cards, versos, etc.)

Citation

<!-- TODO: Add NLS collaborators to citation - Jamie, Sarah, and Rob at minimum. Check with them for full names and preferred citation format. -->

If you use this model, please cite:

@misc{vanstrien2026indexcard,
  author = {van Strien, Daniel},
  title = {Archival Index Card Detector},
  year = {2026},
  publisher = {Hugging Face},
  url = {https://huggingface.co/davanstrien/archival-index-card-detector}
}

License

This model is released under the AGPL-3.0 license (required by the YOLO26 base model license).