First commit.

.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+venv/
+data/images/
+data/masks/
+data/features/
+data/*.zip
+data/.tsne_cache.npz
+*.pt
+*.onnx

Dockerfile

@@ -0,0 +1,15 @@
+FROM python:3.11-slim
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libgl1 libglib2.0-0 git && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /code
+COPY requirements.txt .
+RUN pip install --no-cache-dir torch torchvision --index-url https://download.pytorch.org/whl/cpu \
+    && pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+# Hugging Face Spaces expects the app on port 7860
+EXPOSE 7860
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Timotej Cvikl, Žiga Klun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,69 @@
+# Religious Artwork Analysis
+
+Code for **"Analysis of Artworks Across Different Religions"** — a study of
+whether (and which) visual features separate religious artworks of Buddhism,
+Christianity, Hinduism and Islam, using a hand-verified, balanced dataset of
+3,997 paintings (~1,000 per religion).
+
+- **Dataset**: [Religious Artwork Dataset on Kaggle](https://www.kaggle.com/datasets/zigaklun/religious-artwork-dataset)
+  (3,997 images from 8 museum/archive sources, hand-verified labels, CC BY-NC 4.0)
+- **Live demo**: interactive t-SNE explorer (see [`app/`](app/))
+
+## Key result
+
+Semantic features transfer across museums; style features largely do not.
+Religion-classification accuracy (chance = 0.25):
+
+| feature family        | dims | pooled 5-fold | leave-one-source-out |
+|-----------------------|-----:|--------------:|---------------------:|
+| CLIP attribute scores |   27 |         0.919 |             **0.856** |
+| CLIP embedding        |  512 |         0.941 |                 0.828 |
+| DINOv2 embedding      |  768 |         0.910 |                 0.783 |
+| hand-crafted (all)    |  378 |         0.741 |                 0.391 |
+| pose (main figure)    |   36 |         0.611 |                 0.369 |
+| face composition      |   39 |         0.501 |                 0.280 |
+
+The pooled–LOSO gap measures **source leakage**: features that encode museum
+reproduction style (scan texture, framing) look discriminative pooled but
+collapse on unseen sources. Reproduce with `evaluation/family_accuracy.py`.
+
+## Setup
+
+```bash
+python -m venv venv && source venv/bin/activate
+pip install -r requirements.txt
+
+# 1. data (needs a Kaggle API token)
+python data/download.py
+
+# 2. preprocessing: guarded background masks (~1 h, CPU)
+python preprocessing/generate_masks.py
+
+# 3. features (each checkpointed & resumable)
+python features/extract_handcrafted.py --workers 8
+python features/extract_clip.py
+python features/extract_dino.py
+python features/extract_faces.py
+python features/extract_pose.py
+
+# 4. evaluation table
+python evaluation/family_accuracy.py
+
+# 5. web app
+uvicorn app.main:app --port 8000
+```
+
+## Repository layout
+
+```
+data/           dataset download + expected layout
+preprocessing/  crop_padding + guarded U^2-Net background masking
+features/       one extractor per feature family (see features/README.md)
+evaluation/     pooled vs leave-one-source-out accuracy per family
+app/            FastAPI + Plotly interactive t-SNE explorer
+```
+
+## Authors
+
+Timotej Cvikl & Žiga Klun — Faculty of Computer and Information Science, University of
+Ljubljana. Code under MIT license; dataset under CC BY-NC 4.0 (see the Kaggle page).

app/README.md

@@ -0,0 +1,25 @@
+# Interactive t-SNE explorer
+
+FastAPI + Plotly app: per-family weighted t-SNE over all extracted features,
+with live CLIP zero-shot attribute editing (edit prompts, the server encodes
+them with CLIP and rescores the whole dataset).
+
+## Run locally
+
+Requires `data/` populated (images + feature parquets — see repo README).
+
+```bash
+uvicorn app.main:app --port 8000
+```
+
+First start fits the t-SNE (~a minute) and caches it in `data/.tsne_cache.npz`.
+
+## Deploy as a Hugging Face Space (free)
+
+1. Create a Space (type: **Docker**) at huggingface.co/new-space.
+2. Push this repository to it, with `data/` populated via git-lfs
+   (`git lfs track "data/images/**" "data/features/*.parquet"`).
+3. The included `Dockerfile` does the rest; the Space serves on port 7860.
+
+Note: the CLIP label editor writes `app/clip_labels.json` — on a public
+deployment consider making the Space private or removing write endpoints.

app/clip_labels.json

@@ -0,0 +1,120 @@
+{
+  "christianity": [
+    {
+      "label": "halo",
+      "prompt": "a golden halo around a figure"
+    },
+    {
+      "label": "cross",
+      "prompt": "a crucifix or cross"
+    },
+    {
+      "label": "virgin mary",
+      "prompt": "the virgin mary"
+    },
+    {
+      "label": "angels",
+      "prompt": "angels with wings"
+    },
+    {
+      "label": "nativity",
+      "prompt": "a nativity scene"
+    },
+    {
+      "label": "biblical figs",
+      "prompt": "biblical figures in robes"
+    }
+  ],
+  "islam": [
+    {
+      "label": "calligraphy",
+      "prompt": "arabic calligraphy"
+    },
+    {
+      "label": "arabesque",
+      "prompt": "geometric arabesque patterns"
+    },
+    {
+      "label": "mosque",
+      "prompt": "a mosque with a minaret"
+    },
+    {
+      "label": "quran ms",
+      "prompt": "an illuminated quran manuscript"
+    },
+    {
+      "label": "islamic tiles",
+      "prompt": "islamic tile patterns"
+    }
+  ],
+  "buddhism": [
+    {
+      "label": "buddha",
+      "prompt": "a buddha statue"
+    },
+    {
+      "label": "lotus",
+      "prompt": "a lotus flower"
+    },
+    {
+      "label": "thangka",
+      "prompt": "a thangka painting"
+    },
+    {
+      "label": "mandala",
+      "prompt": "a mandala"
+    },
+    {
+      "label": "dharma wheel",
+      "prompt": "a dharma wheel"
+    },
+    {
+      "label": "bodhisattva",
+      "prompt": "a bodhisattva figure"
+    }
+  ],
+  "hinduism": [
+    {
+      "label": "many-armed",
+      "prompt": "a deity with multiple arms"
+    },
+    {
+      "label": "ganesha",
+      "prompt": "ganesha the elephant god"
+    },
+    {
+      "label": "hindu temple",
+      "prompt": "a colorful hindu temple"
+    },
+    {
+      "label": "krishna",
+      "prompt": "krishna playing the flute"
+    },
+    {
+      "label": "shiva nataraja",
+      "prompt": "dancing shiva nataraja"
+    }
+  ],
+  "general": [
+    {
+      "label": "gold leaf",
+      "prompt": "gold leaf background"
+    },
+    {
+      "label": "prayer",
+      "prompt": "religious figures in prayer"
+    },
+    {
+      "label": "sacred geom.",
+      "prompt": "sacred geometry"
+    },
+    {
+      "label": "ritual objects",
+      "prompt": "incense and ritual objects"
+    },
+    {
+      "label": "manuscript",
+      "prompt": "a religious manuscript"
+    }
+  ]
+}

app/main.py

@@ -0,0 +1,1118 @@
+"""
+Religious Art Space Navigator — FastAPI backend.
+
+Startup: loads features.parquet, normalises feature groups, concatenates them,
+         and fits a single openTSNE projection.
+Serves:  initial embedding, CLIP label editor (GET/POST /api/clip_labels),
+         and on-demand t-SNE recompute (POST /api/recompute).
+
+Run:
+    uvicorn app.main:app --reload --port 8000
+"""
+
+import hashlib
+import json
+import os
+import time
+from contextlib import asynccontextmanager
+
+import clip as openai_clip
+import cv2
+import numpy as np
+import pandas as pd
+import torch
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import FileResponse, Response
+from fastapi.staticfiles import StaticFiles
+from openTSNE import TSNE
+from pydantic import BaseModel
+from scipy.spatial import ConvexHull, Delaunay
+from sklearn.cluster import HDBSCAN
+from sklearn.decomposition import PCA
+from sklearn.preprocessing import StandardScaler
+
+FEATURES_PARQUET  = "features/handcrafted_gold.parquet"   # Timotej's HC file (joins via metadata id)
+DINO_PARQUET      = "data/features_dino.parquet"
+CLIP_PARQUET      = "data/features_clip.parquet"
+POSE_PARQUET      = "data/features_pose.parquet"
+FACES_PARQUET     = "data/features_faces.parquet"
+METADATA_CSV      = "data/artwork_metadata.csv"
+IMAGES_DIR        = "data/images"
+CACHE_PATH        = "data/.tsne_cache.npz"
+CLIP_LABELS_PATH      = "app/clip_labels.json"
+CLIP_SCORE_THRESHOLD  = 0.22   # zero out scores below this before normalisation
+_CACHE_VERSION        = "v5"
+
+FACE_FEATURE_COLS = [
+    "face_count", "face_detected", "face_coverage",
+    "mean_face_size", "max_face_size", "face_centroid_x",
+    "face_centroid_y", "face_size_std", "mean_face_angle",
+]
+
+HC_SUBGROUPS = {
+    "hc_color":    ["hc_hist_", "hc_norm_hist_", "hc_h_hist_", "hc_s_hist_", "hc_v_hist_",
+                    "hc_avg_hue", "hc_avg_sat"],
+    "hc_flat":     ["hc_flatness_"],
+    "hc_geom":     ["hc_lbp_", "hc_fft_band_"],
+    "hc_lines":    ["hc_angle_hist_", "hc_hough_", "hc_straight_ratio"],
+    "hc_light":    ["hc_brightness", "hc_contrast", "hc_darkness", "hc_edge_density"],
+    "hc_symmetry": ["hc_sym_"],
+}
+
+POSE_CONNECTIONS = [
+    (0,1),(1,2),(2,3),(3,7),(0,4),(4,5),(5,6),(6,8),(9,10),
+    (11,12),(11,13),(13,15),(15,17),(15,19),(17,19),
+    (12,14),(14,16),(16,18),(16,20),(18,20),
+    (11,23),(12,24),(23,24),
+    (23,25),(25,27),(27,29),(27,31),(29,31),
+    (24,26),(26,28),(28,30),(28,32),(30,32),
+]
+
+def _load_clip_labels() -> tuple[list[str], list[str], dict]:
+    """Read clip_labels.json → (CLIP_LABELS flat, ATTRIBUTES flat, raw dict)."""
+    with open(CLIP_LABELS_PATH) as f:
+        raw = json.load(f)
+    labels, prompts = [], []
+    for entries in raw.values():
+        for e in entries:
+            labels.append(e["label"])
+            prompts.append(e["prompt"])
+    return labels, prompts, raw
+
+
+CLIP_LABELS, _CLIP_ATTRIBUTES, _ = _load_clip_labels()
+
+state = {}
+
+
+def _norm(arr: np.ndarray) -> np.ndarray:
+    scaled = StandardScaler().fit_transform(arr.astype(np.float32))
+    return scaled / np.sqrt(scaled.shape[1])
+
+
+def _file_hash(path: str) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()[:16]
+
+
+def _cache_key() -> str:
+    parts = [_CACHE_VERSION]
+    for p in (FEATURES_PARQUET, DINO_PARQUET, CLIP_PARQUET, POSE_PARQUET, FACES_PARQUET, CLIP_LABELS_PATH):
+        if os.path.exists(p):
+            parts.append(_file_hash(p))
+    return ":".join(parts)
+
+
+def _encode_clip_prompts(prompts: list[str]) -> np.ndarray:
+    """Encode text prompts with CLIP text encoder → (n_prompts, 512) float32."""
+    model, _ = state.get("_clip_model_pair") or (None, None)
+    if model is None:
+        device = "cuda" if torch.cuda.is_available() else "cpu"
+        model, _ = openai_clip.load("ViT-B/16", device=device)
+        state["_clip_model_pair"] = (model, device)
+    device = state["_clip_model_pair"][1]
+    with torch.no_grad():
+        tokens = openai_clip.tokenize(prompts).to(device)
+        text_feats = model.encode_text(tokens).float()
+        text_feats /= text_feats.norm(dim=-1, keepdim=True)
+    return text_feats.cpu().numpy()
+
+
+def _recompute_clip_scores(image_vecs: np.ndarray, prompts: list[str],
+                           threshold: float = 0.0) -> np.ndarray:
+    """Dot-product stored image embeddings against re-encoded prompts.
+    Scores below threshold are zeroed out (sparse, discriminative representation)."""
+    text_feats = _encode_clip_prompts(prompts)
+    scores = (image_vecs @ text_feats.T).astype(np.float32)
+    if threshold > 0:
+        scores[scores < threshold] = 0.0
+    return scores
+
+
+def _run_tsne() -> None:
+    """Rebuild concatenated feature matrix and fit a single openTSNE. Updates state['coords']."""
+    t0 = time.time()
+    blocks = []
+    group_names = []
+
+    for name in HC_SUBGROUPS:
+        if state.get(name) is not None:
+            blocks.append(state[name])
+            group_names.append(name)
+
+    for name in ("dino", "clip_v"):
+        if state.get(name) is not None:
+            blocks.append(state[name])
+            group_names.append(name)
+
+    # CLIP scores: always recompute from current prompts so label edits take effect
+    _, prompts, _ = _load_clip_labels()
+    image_vecs = state.get("_clip_image_vecs")
+    if image_vecs is not None and len(prompts) > 0:
+        thr = state.get("clip_threshold", CLIP_SCORE_THRESHOLD)
+        clip_s = _norm(_recompute_clip_scores(image_vecs, prompts, threshold=thr))
+        blocks.append(clip_s)
+        state["clip_s"] = clip_s
+        group_names.append("clip_s")
+    else:
+        state["clip_s"] = None
+        if len(prompts) == 0:
+            print("  clip_s: skipped (no labels defined)")
+
+    for name in ("pose", "faces"):
+        if state.get(name) is not None:
+            blocks.append(state[name])
+            group_names.append(name)
+
+    X = np.concatenate(blocks, axis=1)
+    print(f"  t-SNE input: {X.shape} ({len(group_names)} groups: {group_names})")
+
+    X50 = PCA(n_components=min(50, X.shape[1]), random_state=42).fit_transform(X)
+    coords = np.array(
+        TSNE(n_components=2, perplexity=40, n_jobs=-1,
+             initialization="pca", random_state=42).fit(X50),
+        dtype=np.float32,
+    )
+    state["coords"] = coords
+    print(f"  t-SNE done in {time.time() - t0:.1f}s")
+
+
+def load_and_fit():
+    # ── CLIP (required — has filename + religion) ──────────────────────────────
+    print("Loading CLIP features ...")
+    clip_df = pd.read_parquet(CLIP_PARQUET)
+    base_df = clip_df[["filename", "religion"]].copy()
+
+    state["clip_v"] = _norm(np.stack(clip_df["clip_vector"].tolist()))
+    state["_clip_image_vecs"] = np.stack(clip_df["clip_vector"].tolist()).astype(np.float32)
+    state["clip_s"] = _norm(np.stack(clip_df["clip_scores"].tolist()))
+    print(f"  CLIP: {len(clip_df)} images")
+
+    # ── DINO (required) ────────────────────────────────────────────────────────
+    print("Loading DINO features ...")
+    dino_df = pd.read_parquet(DINO_PARQUET)[["filename", "dino_vector"]]
+    base_df = base_df.merge(dino_df, on="filename", how="left")
+    state["dino"] = _norm(np.stack(base_df["dino_vector"].tolist()))
+    print(f"  DINO: {state['dino'].shape[1]} dims")
+    base_df = base_df.drop(columns=["dino_vector"])
+
+    # ── Handcrafted (optional — from features.parquet when Timotej adds it) ───
+    for name in HC_SUBGROUPS:
+        state[name] = None
+        state[name + "_cols"] = []
+
+    if os.path.exists(FEATURES_PARQUET):
+        print("Loading handcrafted features ...")
+        hc_df = pd.read_parquet(FEATURES_PARQUET)
+        # HC parquet uses 'id' (metadata.csv row index) — resolve to filename via metadata
+        meta_ids = pd.read_csv(METADATA_CSV, dtype=str)[["id", "filename"]]
+        hc_df = hc_df.merge(meta_ids, on="id", how="left").drop(columns=["id"], errors="ignore")
+        # Drop non-feature columns before merge
+        hc_df = hc_df.drop(columns=["hc_fg_applied"], errors="ignore")
+        base_df = base_df.merge(hc_df, on="filename", how="left")
+        hc_cols = [c for c in base_df.columns if c.startswith("hc_")]
+        for name, prefixes in HC_SUBGROUPS.items():
+            cols = [c for c in hc_cols if any(c.startswith(p) for p in prefixes)]
+            if not cols:
+                print(f"  {name}: no columns matched")
+                continue
+            state[name] = _norm(base_df[cols].fillna(0).values)
+            state[name + "_cols"] = cols
+            print(f"  {name}: {len(cols)} dims")
+    else:
+        print("  handcrafted_gold.parquet not found — HC features skipped")
+
+    # ── Pose ───────────────────────────────────────────────────────────────────
+    state["pose"] = None
+    if os.path.exists(POSE_PARQUET):
+        pose_cols = ["filename", "pose_vector"]
+        _pdf = pd.read_parquet(POSE_PARQUET)
+        if "pose_detected" in _pdf.columns:
+            pose_cols.append("pose_detected")
+        pose_df = _pdf[pose_cols]
+        base_df = base_df.merge(pose_df, on="filename", how="left")
+        # pose_vector stays in base_df for the viz fast-reject; pose_detected too
+        pose_raw = np.stack(base_df["pose_vector"].tolist())
+        if pose_raw.std() > 0:
+            state["pose"] = _norm(pose_raw)
+            print(f"  pose: {state['pose'].shape[1]} dims")
+
+    # ── Faces ──────────────────────────────────────────────────────────────────
+    state["faces"] = None
+    if os.path.exists(FACES_PARQUET):
+        # Load face_vector for features + face_detected/face_count for viz fast-reject
+        face_df = pd.read_parquet(FACES_PARQUET)[["filename", "face_vector", "face_detected", "face_count"]]
+        base_df = base_df.merge(face_df, on="filename", how="left")
+        if "face_vector" in base_df.columns:
+            face_raw = np.stack(base_df["face_vector"].tolist())
+            # Zero-face rows (no detection) would all collapse to the same point
+            # after StandardScaler → PCA line artifact. Add tiny jitter so they
+            # spread naturally in t-SNE while still being distinct from real faces.
+            zero_mask = (face_raw == 0).all(axis=1)
+            if zero_mask.any():
+                rng = np.random.default_rng(42)
+                face_raw[zero_mask] += rng.normal(0, 1e-3, (zero_mask.sum(), face_raw.shape[1]))
+            if face_raw.std() > 0:
+                state["faces"] = _norm(face_raw)
+                n_det = int((~zero_mask).sum())
+                print(f"  faces: {state['faces'].shape[1]} dims ({n_det} detected, {zero_mask.sum()} no-face jittered)")
+        # face_detected/face_count stay in base_df for viz fast-reject via _raw_df
+
+    # ── Metadata ───────────────────────────────────────────────────────────────
+    meta_cols = ["filename", "title", "artist", "year"]
+    try:
+        meta    = pd.read_csv(METADATA_CSV, dtype=str)[meta_cols]
+        base_df = base_df.merge(meta, on="filename", how="left")
+    except Exception as e:
+        print(f"  metadata.csv join skipped: {e}")
+
+    keep = ["filename", "religion", "sub_religion", "source", "title", "artist", "year"]
+    state["meta"]    = base_df[[c for c in keep if c in base_df.columns]].reset_index(drop=True)
+    state["_raw_df"] = base_df.reset_index(drop=True)
+
+    # Try cache (keyed on parquet hashes + clip_labels.json)
+    cache_key = _cache_key()
+    if os.path.exists(CACHE_PATH):
+        try:
+            z = np.load(CACHE_PATH)
+            if str(z["__key__"]) == cache_key:
+                state["coords"] = z["coords"]
+                print(f"Loaded t-SNE from cache ({CACHE_PATH})")
+                print(f"Ready — {len(base_df)} images.")
+                return
+            else:
+                print("  cache key mismatch — will recompute t-SNE")
+        except Exception as e:
+            print(f"  cache read failed ({e}) — will recompute")
+
+    _run_tsne()
+
+    np.savez_compressed(CACHE_PATH, __key__=cache_key, coords=state["coords"])
+    print(f"  saved t-SNE cache → {CACHE_PATH}")
+    print(f"Ready — {len(base_df)} images.")
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    load_and_fit()
+    yield
+
+
+app = FastAPI(lifespan=lifespan)
+app.mount("/static", StaticFiles(directory="app/static"), name="static")
+app.mount("/images", StaticFiles(directory=IMAGES_DIR),  name="images")
+
+
+@app.get("/")
+def root():
+    return FileResponse("app/static/index.html")
+
+
+@app.get("/api/embeddings")
+def embeddings():
+    meta   = state["meta"]
+    coords = state["coords"]
+    rows   = meta.to_dict("records")
+    for i, row in enumerate(rows):
+        row["x"] = float(coords[i, 0])
+        row["y"] = float(coords[i, 1])
+        for k, v in row.items():
+            if isinstance(v, float) and np.isnan(v):
+                row[k] = ""
+    return rows
+
+
+class Weights(BaseModel):
+    hc_color:    float = 1.0
+    hc_flat:     float = 1.0
+    hc_geom:     float = 1.0
+    hc_lines:    float = 1.0
+    hc_light:    float = 1.0
+    hc_symmetry: float = 1.0
+    dino:        float = 1.0
+    clip_v:      float = 1.0
+    clip_s:      float = 1.0
+    pose:        float = 1.0
+    faces:       float = 1.0
+
+
+@app.post("/api/reproject")
+def reproject(w: Weights):
+    weights = w.model_dump()
+    t0 = time.time()
+
+    blocks = []
+    for name in [*HC_SUBGROUPS.keys(), "dino", "clip_v", "clip_s", "pose", "faces"]:
+        arr = state.get(name)
+        if arr is None:
+            continue
+        weight = weights.get(name, 1.0)
+        if weight <= 0:
+            continue
+        blocks.append(arr * weight)
+
+    if not blocks:
+        coords = state["coords"]
+    else:
+        X = np.concatenate(blocks, axis=1)
+        X50 = PCA(n_components=min(50, X.shape[1]), random_state=42).fit_transform(X)
+        coords = np.array(
+            TSNE(n_components=2, perplexity=40, n_jobs=-1,
+                 initialization="pca", random_state=42).fit(X50),
+            dtype=np.float32,
+        )
+        state["coords"] = coords  # keep in sync so clusters match
+
+    print(f"  reproject done in {time.time() - t0:.1f}s")
+    return [{"x": float(x), "y": float(y)} for x, y in coords]
+
+
+class ClipLabelEntry(BaseModel):
+    label:  str
+    prompt: str
+
+class ClipLabelsBody(BaseModel):
+    christianity: list[ClipLabelEntry] = []
+    islam:        list[ClipLabelEntry] = []
+    buddhism:     list[ClipLabelEntry] = []
+    hinduism:     list[ClipLabelEntry] = []
+    general:      list[ClipLabelEntry] = []
+
+
+@app.get("/api/clip_labels")
+def get_clip_labels():
+    with open(CLIP_LABELS_PATH) as f:
+        return json.load(f)
+
+
+@app.post("/api/clip_labels")
+def set_clip_labels(body: ClipLabelsBody):
+    raw = body.model_dump()
+    # Validate: every entry must have non-empty label and prompt
+    for religion, entries in raw.items():
+        for e in entries:
+            if not e["label"].strip() or not e["prompt"].strip():
+                raise HTTPException(400, f"Empty label or prompt in {religion}")
+
+    with open(CLIP_LABELS_PATH, "w") as f:
+        json.dump(raw, f, indent=2)
+
+    # Refresh global CLIP_LABELS list
+    global CLIP_LABELS, _CLIP_ATTRIBUTES
+    CLIP_LABELS, _CLIP_ATTRIBUTES, _ = _load_clip_labels()
+
+    t0 = time.time()
+    _run_tsne()
+    np.savez_compressed(CACHE_PATH, __key__=_cache_key(), coords=state["coords"])
+    coords = state["coords"]
+    return {
+        "ok": True,
+        "n_labels": len(CLIP_LABELS),
+        "duration_s": round(time.time() - t0, 1),
+        "points": [{"x": float(x), "y": float(y)} for x, y in coords],
+    }
+
+
+@app.get("/api/clip_threshold")
+def get_clip_threshold():
+    return {"threshold": state.get("clip_threshold", CLIP_SCORE_THRESHOLD)}
+
+
+class ThresholdBody(BaseModel):
+    threshold: float
+
+
+@app.post("/api/clip_threshold")
+def set_clip_threshold(body: ThresholdBody):
+    thr = max(0.0, min(float(body.threshold), 1.0))
+    state["clip_threshold"] = thr
+    _run_tsne()
+    np.savez_compressed(CACHE_PATH, __key__=_cache_key(), coords=state["coords"])
+    coords = state["coords"]
+    return {"ok": True, "points": [{"x": float(x), "y": float(y)} for x, y in coords]}
+
+
+@app.post("/api/recompute")
+def recompute():
+    t0 = time.time()
+    _run_tsne()
+    np.savez_compressed(CACHE_PATH, __key__=_cache_key(), coords=state["coords"])
+    coords = state["coords"]
+    return {
+        "ok": True,
+        "duration_s": round(time.time() - t0, 1),
+        "points": [{"x": float(x), "y": float(y)} for x, y in coords],
+    }
+
+
+def _smart_cluster(coords: np.ndarray) -> np.ndarray:
+    """Density-based clustering on the 2D blended layout — matches what the
+    user sees. HDBSCAN with EOM selection gives variable cluster sizes; small
+    `min_samples` + moderate `min_cluster_size` surfaces the visible islands
+    (including elongated/curved shapes) without fragmenting the dense cores.
+    Returns int labels where -1 = noise."""
+    n = len(coords)
+    min_cluster_size = max(30, n // 100)
+
+    hdb = HDBSCAN(
+        min_cluster_size=min_cluster_size,
+        min_samples=8,
+        cluster_selection_method="eom",
+    )
+    labels = hdb.fit_predict(coords)
+
+    n_clusters = int(labels.max()) + 1 if labels.max() >= 0 else 0
+    n_noise = int((labels == -1).sum())
+    print(f"  HDBSCAN: {n_clusters} clusters, {n_noise}/{n} noise "
+          f"(min_cluster_size={min_cluster_size})")
+    return labels
+
+
+def _grow_clusters(coords: np.ndarray, labels: np.ndarray,
+                   factor: float = 3.0) -> np.ndarray:
+    """Halo pass: any orphan (noise) point whose nearest cluster member is
+    within `factor` × the global median nearest-neighbour distance gets
+    absorbed by that cluster. Two iterations, so once-removed neighbours
+    can join via the newly-grown halo — but the threshold is frozen on
+    iteration 1 to prevent runaway growth across density gaps."""
+    if labels.max() < 0:
+        return labels
+    from sklearn.neighbors import NearestNeighbors
+
+    nn_global = NearestNeighbors(n_neighbors=2).fit(coords)
+    d_global, _ = nn_global.kneighbors(coords)
+    threshold = float(np.median(d_global[:, 1])) * factor
+
+    new_labels = labels.copy()
+    for it in range(2):
+        core_mask = new_labels >= 0
+        if not core_mask.any():
+            break
+        noise_idx = np.flatnonzero(new_labels == -1)
+        if len(noise_idx) == 0:
+            break
+
+        nn = NearestNeighbors(n_neighbors=1).fit(coords[core_mask])
+        core_labels = new_labels[core_mask]
+        dists, idxs = nn.kneighbors(coords[noise_idx])
+
+        grown = 0
+        for ni, dist, nearest in zip(noise_idx, dists[:, 0], idxs[:, 0]):
+            if dist <= threshold:
+                new_labels[ni] = int(core_labels[nearest])
+                grown += 1
+        print(f"  halo pass {it+1}: pulled in {grown}/{len(noise_idx)} orphans "
+              f"(threshold={threshold:.4f})")
+        if grown == 0:
+            break
+    return new_labels
+
+
+def _circumradius(a, b, c) -> float:
+    """Circumradius of triangle (a, b, c). Returns inf for degenerate ones."""
+    ax, ay = a; bx, by = b; cx, cy = c
+    d = 2.0 * (ax * (by - cy) + bx * (cy - ay) + cx * (ay - by))
+    if abs(d) < 1e-12:
+        return float("inf")
+    a2 = ax * ax + ay * ay
+    b2 = bx * bx + by * by
+    c2 = cx * cx + cy * cy
+    ux = (a2 * (by - cy) + b2 * (cy - ay) + c2 * (ay - by)) / d
+    uy = (a2 * (cx - bx) + b2 * (ax - cx) + c2 * (bx - ax)) / d
+    return float(np.hypot(ux - ax, uy - ay))
+
+
+def _alpha_ring(pts: np.ndarray, alpha_mult: float = 2.0):
+    """Concave-hull outline via alpha-shape (Delaunay triangles with small
+    circumradius). Returns a closed ring of [x, y] vertices, or None on
+    failure — caller should fall back to convex hull."""
+    if len(pts) < 4:
+        return None
+    try:
+        tri = Delaunay(pts)
+    except Exception:
+        return None
+
+    radii = np.array([_circumradius(*pts[s]) for s in tri.simplices])
+    finite = radii[np.isfinite(radii)]
+    if len(finite) == 0:
+        return None
+    threshold = float(np.median(finite)) * alpha_mult
+
+    edge_count: dict[tuple[int, int], int] = {}
+    for ti, s in enumerate(tri.simplices):
+        if radii[ti] > threshold:
+            continue
+        for i, j in ((0, 1), (1, 2), (2, 0)):
+            a, b = int(s[i]), int(s[j])
+            key = (a, b) if a < b else (b, a)
+            edge_count[key] = edge_count.get(key, 0) + 1
+    boundary = [e for e, c in edge_count.items() if c == 1]
+    if len(boundary) < 3:
+        return None
+
+    # Walk the boundary edges into rings; return the longest ring.
+    adj: dict[int, list[int]] = {}
+    for a, b in boundary:
+        adj.setdefault(a, []).append(b)
+        adj.setdefault(b, []).append(a)
+
+    used: set[tuple[int, int]] = set()
+    rings: list[list[int]] = []
+    for start in list(adj):
+        # find any unused edge starting at this vertex
+        for first in adj[start]:
+            key = (start, first) if start < first else (first, start)
+            if key in used:
+                continue
+            used.add(key)
+            path = [start, first]
+            cur, prev = first, start
+            while cur != start:
+                nxt = None
+                for n in adj.get(cur, ()):
+                    if n == prev:
+                        continue
+                    k = (cur, n) if cur < n else (n, cur)
+                    if k in used:
+                        continue
+                    nxt = n
+                    used.add(k)
+                    break
+                if nxt is None:
+                    break
+                path.append(nxt)
+                prev, cur = cur, nxt
+            if len(path) >= 4 and path[-1] == start:
+                rings.append(path)
+
+    if not rings:
+        return None
+    rings.sort(key=len, reverse=True)
+    return [pts[i].tolist() for i in rings[0]]
+
+
+def _core_hull(pts: np.ndarray, pct: float = 75.0):
+    """Convex hull using only points within the pct-th percentile distance
+    from the cluster centroid, avoiding outlier-stretched polygons."""
+    centroid = pts.mean(axis=0)
+    dists = np.linalg.norm(pts - centroid, axis=1)
+    threshold = np.percentile(dists, pct)
+    core = pts[dists <= threshold]
+    if len(core) < 3:
+        core = pts  # fall back to all points
+    try:
+        hull  = ConvexHull(core)
+        verts = core[hull.vertices].tolist()
+        verts.append(verts[0])
+        return verts
+    except Exception:
+        mn, mx = core.min(axis=0), core.max(axis=0)
+        return [[mn[0],mn[1]],[mx[0],mn[1]],[mx[0],mx[1]],[mn[0],mn[1]]]
+
+
+def _cluster_outline(pts: np.ndarray):
+    """Prefer alpha-shape (concave); fall back to convex hull if it fails."""
+    ring = _alpha_ring(pts)
+    if ring is not None and len(ring) >= 4:
+        return ring
+    return _core_hull(pts)
+
+
+# ── Per-group cluster label generators ───────────────────────────────────────
+
+def _label_color(mask: np.ndarray) -> str | None:
+    df = state["_raw_df"]
+    cols = state.get("hc_color_cols", [])
+    hue_cols = [c for c in cols if "avg_hue" in c]
+    sat_cols = [c for c in cols if "avg_sat" in c]
+    parts = []
+    if hue_cols:
+        hue = df[hue_cols[0]].values[mask].mean()
+        if hue < 30 or hue > 330:
+            parts.append("warm reds/oranges")
+        elif hue < 90:
+            parts.append("yellows/greens")
+        elif hue < 180:
+            parts.append("cool greens/cyans")
+        else:
+            parts.append("blues/purples")
+    if sat_cols:
+        sat = df[sat_cols[0]].values[mask].mean()
+        parts.append("vibrant" if sat > 0.45 else "muted/desaturated")
+    return " · ".join(parts) if parts else None
+
+
+def _label_flat(mask: np.ndarray) -> str | None:
+    df = state["_raw_df"]
+    cols = [c for c in state.get("hc_flat_cols", []) if "flatness" in c]
+    if not cols:
+        return None
+    val = df[cols].values[mask].mean()
+    # higher flatness std → more painterly; lower → flatter fills
+    return "flat color fills" if val < 0.08 else "painterly gradients"
+
+
+def _label_geom(mask: np.ndarray) -> str | None:
+    df = state["_raw_df"]
+    cols = state.get("hc_geom_cols", [])
+    fft_cols = [c for c in cols if "fft_band" in c]
+    lbp_cols = [c for c in cols if "lbp_" in c]
+    parts = []
+    if fft_cols:
+        bands = df[fft_cols].values[mask].mean(axis=0)
+        mid = bands[2:5].sum()
+        low = bands[:2].sum() + 1e-10
+        if mid / low > 1.5:
+            parts.append("repeating geometric patterns")
+    if lbp_cols:
+        lbp = df[lbp_cols].values[mask].mean(axis=0)
+        # entropy as proxy for texture complexity
+        p = lbp / (lbp.sum() + 1e-10)
+        entropy = float(-np.sum(p * np.log(p + 1e-10)))
+        parts.append("complex texture" if entropy > 3.5 else "uniform texture")
+    return " · ".join(parts) if parts else None
+
+
+def _label_lines(mask: np.ndarray) -> str | None:
+    df = state["_raw_df"]
+    cols = state.get("hc_lines_cols", [])
+    count_cols = [c for c in cols if "hough_count" in c]
+    ratio_cols = [c for c in cols if "straight_ratio" in c]
+    angle_cols = [c for c in cols if "angle_hist_" in c]
+    parts = []
+    if count_cols and ratio_cols:
+        count = df[count_cols[0]].values[mask].mean()
+        ratio = df[ratio_cols[0]].values[mask].mean()
+        if count > 5 and ratio > 0.4:
+            parts.append("strong straight lines")
+        elif ratio < 0.2:
+            parts.append("curved/organic lines")
+    if angle_cols:
+        angles = df[angle_cols].values[mask].mean(axis=0)
+        dom = int(np.argmax(angles))
+        direction = ["horizontal","diagonal↗","vertical","diagonal↘",
+                     "horizontal","diagonal↗","vertical","diagonal↘"]
+        parts.append(f"dominant {direction[dom]} lines")
+    return " · ".join(parts) if parts else None
+
+
+def _label_light(mask: np.ndarray) -> str | None:
+    df = state["_raw_df"]
+    cols = state.get("hc_light_cols", [])
+    bright_cols  = [c for c in cols if "brightness" in c]
+    contrast_cols= [c for c in cols if "contrast"   in c]
+    dark_cols    = [c for c in cols if "darkness"   in c]
+    parts = []
+    if bright_cols:
+        b = df[bright_cols[0]].values[mask].mean()
+        if b > 0.6:   parts.append("bright")
+        elif b < 0.3: parts.append("dark")
+    if dark_cols:
+        d = df[dark_cols[0]].values[mask].mean()
+        if d > 0.5: parts.append("heavy shadows")
+    if contrast_cols:
+        c = df[contrast_cols[0]].values[mask].mean()
+        parts.append("high contrast" if c > 0.5 else "low contrast")
+    return " · ".join(parts) if parts else None
+
+
+def _label_symmetry(mask: np.ndarray) -> str | None:
+    df = state["_raw_df"]
+    cols = state.get("hc_symmetry_cols", [])
+    lr_cols = [c for c in cols if "sym_lr" in c or "sym_h" in c]
+    tb_cols = [c for c in cols if "sym_tb" in c or "sym_v" in c]
+    parts = []
+    if lr_cols:
+        s = df[lr_cols[0]].values[mask].mean()
+        parts.append("left-right symmetric" if s > 0.85 else "asymmetric")
+    if tb_cols:
+        s = df[tb_cols[0]].values[mask].mean()
+        if s > 0.85: parts.append("top-bottom symmetric")
+    return " · ".join(parts) if parts else None
+
+
+def _label_religion(mask: np.ndarray) -> str | None:
+    meta = state["meta"]
+    if "religion" not in meta.columns:
+        return None
+    counts = meta["religion"].values[mask]
+    unique, cnts = np.unique(counts, return_counts=True)
+    top_frac = cnts.max() / cnts.sum()
+    if top_frac > 0.65:
+        return f"predominantly {unique[cnts.argmax()]}"
+    return None
+
+
+def _label_clip(mask: np.ndarray) -> str | None:
+    clip_s = state.get("clip_s")
+    if clip_s is None:
+        return None
+    dev = clip_s[mask].mean(axis=0)
+    order = np.argsort(dev)[::-1]
+    labels = CLIP_LABELS  # always read the global (updated on label save)
+    picks = [i for i in order if i < len(labels) and dev[i] > 0.05][:2]
+    if not picks:
+        return None
+    return " · ".join(labels[i] for i in picks)
+
+
+def _label_pose(mask: np.ndarray) -> str | None:
+    df = state["_raw_df"]
+    if "pose_detected" not in df.columns:
+        return None
+    ratio = df["pose_detected"].values[mask].mean()
+    if ratio > 0.6:
+        return "figurative (bodies present)"
+    if ratio < 0.2:
+        return "non-figurative"
+    return None
+
+
+def _label_faces(mask: np.ndarray) -> str | None:
+    df = state["_raw_df"]
+    face_cols = [c for c in FACE_FEATURE_COLS if c in df.columns]
+    if not face_cols:
+        return None
+    count_col = [c for c in face_cols if "face_count" in c]
+    if not count_col:
+        return None
+    avg = df[count_col[0]].values[mask].mean()
+    if avg >= 3:
+        return "crowd/group scenes"
+    if avg >= 1:
+        return "portrait/close-up"
+    return "no faces"
+
+
+# Map each group name to its labeller (receives boolean mask, returns str|None)
+_GROUP_LABELLERS = {
+    "hc_color":    _label_color,
+    "hc_flat":     _label_flat,
+    "hc_geom":     _label_geom,
+    "hc_lines":    _label_lines,
+    "hc_light":    _label_light,
+    "hc_symmetry": _label_symmetry,
+    "dino":        _label_religion,
+    "clip_v":      _label_religion,
+    "clip_s":      _label_clip,
+    "pose":        _label_pose,
+    "faces":       _label_faces,
+}
+
+
+def _cluster_label(mask: np.ndarray) -> str:
+    """Collect labels from all active labellers, take top 3 unique."""
+    scores = []
+    for name, labeller in _GROUP_LABELLERS.items():
+        if state.get(name) is None:
+            continue
+        label = labeller(mask)
+        if label:
+            scores.append(label)
+    seen, picks = set(), []
+    for lbl in scores:
+        if lbl not in seen:
+            seen.add(lbl)
+            picks.append(lbl)
+        if len(picks) == 3:
+            break
+    return " · ".join(picks) if picks else "cluster"
+
+
+_CLUSTER_GROUP_SPECS = [
+    ("hc_color",    "Color",      _label_color),
+    ("hc_flat",     "Flatness",   _label_flat),
+    ("hc_geom",     "Geometry",   _label_geom),
+    ("hc_lines",    "Lines",      _label_lines),
+    ("hc_light",    "Light",      _label_light),
+    ("hc_symmetry", "Symmetry",   _label_symmetry),
+    ("clip_s",      "CLIP attr",  _label_clip),
+    ("pose",        "Pose",       _label_pose),
+    ("faces",       "Faces",      _label_faces),
+]
+
+
+@app.post("/api/cluster")
+def cluster():
+    coords = state["coords"]
+    labels = _smart_cluster(coords)
+    labels = _grow_clusters(coords, labels)
+
+    out = []
+    if labels.max() < 0:
+        return {"clusters": out, "point_labels": [-1] * len(coords)}
+
+    meta = state["meta"]
+    has_religion = "religion" in meta.columns
+
+    for cid in range(int(labels.max()) + 1):
+        mask = labels == cid
+        pts  = coords[mask]
+        if len(pts) < 3:
+            continue
+
+        verts    = _cluster_outline(pts)
+        centroid = pts.mean(axis=0)
+        label    = _cluster_label(mask)
+
+        religion_counts = {}
+        if has_religion:
+            vals, counts = np.unique(meta["religion"].values[mask], return_counts=True)
+            religion_counts = {str(v): int(c) for v, c in zip(vals, counts)}
+
+        descriptions = []
+        for _, human_name, labeller in _CLUSTER_GROUP_SPECS:
+            lbl = labeller(mask)
+            if lbl:
+                descriptions.append({"group": human_name, "label": lbl})
+
+        member_idx = np.flatnonzero(mask)
+        rng = np.random.default_rng(cid)
+        k = int(min(6, len(member_idx)))
+        sample_pick = rng.choice(member_idx, size=k, replace=False)
+        samples = [str(meta.iloc[int(i)]["filename"]) for i in sample_pick]
+
+        out.append({
+            "id":              cid,
+            "hull":            verts,
+            "cx":              float(centroid[0]),
+            "cy":              float(centroid[1]),
+            "size":            int(mask.sum()),
+            "label":           label,
+            "religion_counts": religion_counts,
+            "descriptions":    descriptions,
+            "samples":         samples,
+        })
+    # point_labels lets the frontend route any point-click to its cluster
+    # while in cluster mode (-1 = noise → not clickable).
+    return {"clusters": out, "point_labels": [int(x) for x in labels]}
+
+
+# ── Subset stats endpoint (overview / lasso / zoom) ───────────────────────────
+
+class SubsetReq(BaseModel):
+    indices: list[int] | None = None  # None or empty → all points
+
+
+@app.post("/api/subset_info")
+def subset_info(req: SubsetReq):
+    meta = state["meta"]
+    total = len(meta)
+
+    if not req.indices:
+        mask = np.ones(total, dtype=bool)
+    else:
+        mask = np.zeros(total, dtype=bool)
+        valid = [i for i in req.indices if 0 <= i < total]
+        if valid:
+            mask[valid] = True
+
+    n = int(mask.sum())
+    if n == 0:
+        return {"count": 0, "religion_counts": {}, "descriptions": [], "samples": []}
+
+    religion_counts = {}
+    if "religion" in meta.columns:
+        vals, counts = np.unique(meta["religion"].values[mask], return_counts=True)
+        religion_counts = {str(v): int(c) for v, c in zip(vals, counts)}
+
+    descriptions = []
+    for _, human_name, labeller in _CLUSTER_GROUP_SPECS:
+        lbl = labeller(mask)
+        if lbl:
+            descriptions.append({"group": human_name, "label": lbl})
+
+    member_idx = np.flatnonzero(mask)
+    rng = np.random.default_rng(int(n))   # deterministic by subset size
+    k = int(min(6, n))
+    pick = rng.choice(member_idx, size=k, replace=False)
+    samples = [str(meta.iloc[int(i)]["filename"]) for i in pick]
+
+    return {
+        "count":           n,
+        "total":           total,
+        "religion_counts": religion_counts,
+        "descriptions":    descriptions,
+        "samples":         samples,
+    }
+
+
+# ── Per-image analysis endpoint ───────────────────────────────────────────────
+
+@app.get("/api/image_info/{filename:path}")
+def image_info(filename: str):
+    df = state["_raw_df"]
+    mask_series = df["filename"] == filename
+    if not mask_series.any():
+        return {}
+    mask = mask_series.values  # numpy bool array, same length as coords
+
+    group_specs = [
+        ("hc_color",    "Color",      _label_color),
+        ("hc_flat",     "Flatness",   _label_flat),
+        ("hc_geom",     "Geometry",   _label_geom),
+        ("hc_lines",    "Lines",      _label_lines),
+        ("hc_light",    "Light",      _label_light),
+        ("hc_symmetry", "Symmetry",   _label_symmetry),
+        ("clip_s",      "CLIP attr",  _label_clip),
+        ("pose",        "Pose",       _label_pose),
+        ("faces",       "Faces",      _label_faces),
+    ]
+    descriptions = []
+    for _, human_name, labeller in group_specs:
+        lbl = labeller(mask)
+        if lbl:
+            descriptions.append({"group": human_name, "label": lbl})
+
+    # Key scalar values (raw, un-normalised)
+    idx = mask_series[mask_series].index[0]
+    scalars = {}
+    wanted = {
+        "hc_brightness":    "Brightness",
+        "hc_contrast":      "Contrast",
+        "hc_darkness":      "Darkness",
+        "hc_edge_density":  "Edge density",
+        "hc_avg_hue":       "Avg hue",
+        "hc_avg_sat":       "Avg saturation",
+        "hc_straight_ratio":"Straight ratio",
+        "hc_hough_count":   "Hough lines",
+        "face_count":       "Faces",
+        "face_coverage":    "Face coverage",
+        "pose_detected":    "Pose detected",
+    }
+    for col, name in wanted.items():
+        if col in df.columns:
+            val = df.loc[idx, col]
+            try:
+                fval = float(val)
+                if not np.isnan(fval):
+                    scalars[name] = round(fval, 3)
+            except (TypeError, ValueError):
+                pass
+
+    return {"descriptions": descriptions, "scalars": scalars}
+
+
+# ── Visualisation image endpoints ─────────────────────────────────────────────
+
+YUNET_MODEL_PATH = os.path.join("features", "models", "face_detection_yunet_2023mar.onnx")
+_yolo_pose_model = None
+
+
+def _get_yolo():
+    global _yolo_pose_model
+    if _yolo_pose_model is not None:
+        return _yolo_pose_model
+    try:
+        from ultralytics import YOLO
+        _yolo_pose_model = YOLO("yolov8m-pose.pt")
+        print("  YOLOv8-Pose ready (viz)")
+    except Exception as e:
+        print(f"  YOLOv8 init failed: {e}")
+    return _yolo_pose_model
+
+
+def _load_image(filename: str):
+    path = os.path.join(IMAGES_DIR, filename)
+    img = cv2.imread(path)
+    return img  # BGR or None
+
+
+def _encode_jpg(img: np.ndarray, max_px: int = 800) -> bytes:
+    h, w = img.shape[:2]
+    scale = min(max_px / w, max_px / h, 1.0)
+    if scale < 1.0:
+        img = cv2.resize(img, (int(w * scale), int(h * scale)),
+                         interpolation=cv2.INTER_AREA)
+    _, buf = cv2.imencode(".jpg", img, [cv2.IMWRITE_JPEG_QUALITY, 82])
+    return buf.tobytes()
+
+
+@app.get("/api/viz/canny/{filename:path}")
+def viz_canny(filename: str):
+    img = _load_image(filename)
+    if img is None:
+        return Response(status_code=404)
+    gray  = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+    gray  = cv2.GaussianBlur(gray, (5, 5), 0)
+    edges = cv2.Canny(gray, 80, 200)
+    out   = cv2.cvtColor(edges, cv2.COLOR_GRAY2BGR)
+    return Response(content=_encode_jpg(out), media_type="image/jpeg")
+
+
+@app.get("/api/viz/pose/{filename:path}")
+def viz_pose(filename: str):
+    # Fast-reject using stored pose_detected flag
+    df   = state["_raw_df"]
+    rows = df[df["filename"] == filename]
+    if rows.empty:
+        return Response(status_code=404)
+    if "pose_detected" in df.columns and not bool(rows.iloc[0].get("pose_detected", 1)):
+        return Response(status_code=404)
+
+    img = _load_image(filename)
+    if img is None:
+        return Response(status_code=404)
+
+    model = _get_yolo()
+    if model is None:
+        return Response(status_code=404)
+
+    # Re-run YOLOv8 on the original image — same as preview_pose.py
+    results = model(img, verbose=False, conf=0.15)
+    annotated = results[0].plot(kpt_radius=4, line_width=2)  # BGR
+
+    if not any(r.keypoints is not None and len(r.keypoints) > 0 for r in results):
+        return Response(status_code=404)
+
+    return Response(content=_encode_jpg(annotated), media_type="image/jpeg")
+
+
+# YuNet landmark colour order: R.eye, L.eye, nose, R.mouth, L.mouth
+_LM_COLORS = [(0, 255, 0), (0, 0, 255), (255, 0, 0), (0, 255, 255), (255, 255, 0)]
+
+
+@app.get("/api/viz/faces/{filename:path}")
+def viz_faces(filename: str):
+    # Fast-reject using stored face_detected flag
+    df   = state["_raw_df"]
+    rows = df[df["filename"] == filename]
+    if rows.empty:
+        return Response(status_code=404)
+    if "face_detected" in df.columns and not bool(rows.iloc[0].get("face_detected", 1)):
+        return Response(status_code=404)
+
+    if not os.path.exists(YUNET_MODEL_PATH):
+        return Response(status_code=404)
+
+    img = _load_image(filename)
+    if img is None:
+        return Response(status_code=404)
+
+    h, w = img.shape[:2]
+    # YuNet must be initialised at the actual image size — same as preview_faces.py
+    det = cv2.FaceDetectorYN.create(
+        YUNET_MODEL_PATH, "", (w, h),
+        score_threshold=0.7, nms_threshold=0.3,
+    )
+    _, faces = det.detect(img)
+    if faces is None or len(faces) == 0:
+        return Response(status_code=404)
+
+    # Desaturate background so boxes pop
+    gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+    bg   = cv2.cvtColor(gray, cv2.COLOR_GRAY2BGR)
+    bg   = cv2.addWeighted(bg, 0.82, img, 0.18, 0)
+
+    for f in faces:
+        x, y, fw, fh = int(f[0]), int(f[1]), int(f[2]), int(f[3])
+        cv2.rectangle(bg, (x, y), (x + fw, y + fh), (60, 200, 255), 2, cv2.LINE_AA)
+        for k in range(5):
+            lx, ly = int(f[4 + k * 2]), int(f[5 + k * 2])
+            cv2.circle(bg, (lx, ly), 3, _LM_COLORS[k], -1, cv2.LINE_AA)
+
+    return Response(content=_encode_jpg(bg), media_type="image/jpeg")

app/static/index.html

@@ -0,0 +1,1532 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<title>Religious Art Space</title>
+<script src="https://cdn.plot.ly/plotly-2.27.0.min.js"></script>
+<style>
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+
+  body {
+    background: #111;
+    color: #ddd;
+    font-family: system-ui, sans-serif;
+    display: flex;
+    height: 100vh;
+    overflow: hidden;
+  }
+
+  #plot-wrap { flex: 1; min-width: 0; }
+  /* Win against Plotly's own drag-layer cursor (it sets crosshair). */
+  #plot-wrap.clickable .nsewdrag,
+  #plot-wrap.clickable .cursor-crosshair,
+  #plot-wrap.clickable .cursor-pointer { cursor: pointer !important; }
+
+  #img-panel {
+    width: 400px;
+    background: #1c1c1c;
+    border-right: 1px solid #2a2a2a;
+    padding: 18px 16px;
+    display: flex;
+    flex-direction: column;
+    gap: 10px;
+    overflow-y: auto;
+  }
+  #img-empty {
+    color: #555;
+    font-size: 13px;
+    padding: 40px 0;
+    text-align: center;
+  }
+  #img-content, #cluster-content, #summary-content { display: none; }
+  body.has-image   #summary-content { display: none; }
+  body.has-image   #img-content     { display: flex; flex-direction: column; gap: 0; }
+  body.has-cluster #summary-content { display: none; }
+  body.has-cluster #cluster-content { display: flex; flex-direction: column; gap: 0; }
+  /* Default state: nothing has-* → show the overview/subset summary panel. */
+  body:not(.has-image):not(.has-cluster) #summary-content {
+    display: flex; flex-direction: column; gap: 0;
+  }
+  #img-empty { display: none; }   /* replaced by #summary-content */
+
+  /* Persistent header — Clear button is visible in every panel state. */
+  #panel-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 8px;
+    margin-bottom: 10px;
+  }
+  #panel-header h2 { margin-bottom: 0; }
+  #btn-clear {
+    background: #222;
+    border: 1px solid #333;
+    color: #aaa;
+    font-size: 11px;
+    padding: 4px 10px;
+    border-radius: 4px;
+    cursor: pointer;
+    white-space: nowrap;
+  }
+  #btn-clear:hover { background: #2a2a2a; color: #ddd; }
+
+  /* ── Summary panel ── */
+  #summary-title {
+    font-size: 15px;
+    font-weight: 600;
+    color: #eee;
+    line-height: 1.4;
+    margin-bottom: 6px;
+  }
+  #summary-subtitle {
+    font-size: 12px;
+    color: #888;
+    margin-bottom: 12px;
+  }
+
+  /* ── Cluster panel ── */
+  #cluster-title {
+    font-size: 15px;
+    font-weight: 600;
+    color: #eee;
+    line-height: 1.4;
+    margin-bottom: 6px;
+  }
+  #cluster-subtitle {
+    font-size: 12px;
+    color: #888;
+    margin-bottom: 12px;
+  }
+  .religion-bars {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+    margin-bottom: 4px;
+  }
+  .religion-bar {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    font-size: 11px;
+    color: #aaa;
+  }
+  .religion-bar .rname { flex: 0 0 78px; text-transform: capitalize; }
+  .religion-bar .rtrack {
+    flex: 1;
+    height: 6px;
+    background: #222;
+    border-radius: 3px;
+    overflow: hidden;
+  }
+  .religion-bar .rfill { height: 100%; border-radius: 3px; }
+  .religion-bar .rpct { flex: 0 0 36px; text-align: right; color: #888; font-variant-numeric: tabular-nums; }
+
+  .sample-grid {
+    display: grid;
+    grid-template-columns: repeat(3, 1fr);
+    gap: 6px;
+    margin-top: 4px;
+  }
+  .sample-grid img {
+    width: 100%;
+    aspect-ratio: 1;
+    object-fit: cover;
+    border-radius: 3px;
+    background: #111;
+    cursor: pointer;
+    border: 1px solid #222;
+  }
+  .sample-grid img:hover { border-color: #555; }
+
+  #sidebar {
+    width: 260px;
+    background: #1c1c1c;
+    border-left: 1px solid #2a2a2a;
+    padding: 18px 14px;
+    display: flex;
+    flex-direction: column;
+    gap: 20px;
+    overflow-y: auto;
+  }
+
+  #sidebar-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 8px;
+  }
+  #lang-toggle { display: flex; gap: 1px; border-radius: 4px; overflow: hidden; }
+  .lang-btn {
+    background: #222;
+    border: 1px solid #333;
+    color: #888;
+    font-size: 10px;
+    font-weight: 600;
+    padding: 3px 7px;
+    cursor: pointer;
+    letter-spacing: .5px;
+  }
+  .lang-btn.active { background: #7c3aed22; border-color: #7c3aed; color: #a78bfa; }
+  .lang-btn:hover:not(.active) { background: #2a2a2a; color: #ddd; }
+
+  h1 { font-size: 13px; font-weight: 600; color: #fff; letter-spacing: .5px; }
+  h2 { font-size: 11px; color: #777; text-transform: uppercase; letter-spacing: 1px; margin-bottom: 10px; }
+
+  .slider-row { margin-bottom: 10px; }
+  .slider-row label {
+    display: flex;
+    justify-content: space-between;
+    font-size: 12px;
+    color: #bbb;
+    margin-bottom: 4px;
+  }
+  .slider-row label span.val { color: #fff; font-variant-numeric: tabular-nums; }
+  input[type=range] {
+    -webkit-appearance: none;
+    width: 100%;
+    height: 4px;
+    border-radius: 2px;
+    background: #333;
+    outline: none;
+    cursor: pointer;
+  }
+  input[type=range]::-webkit-slider-thumb {
+    -webkit-appearance: none;
+    width: 14px; height: 14px;
+    border-radius: 50%;
+    background: #888;
+    cursor: pointer;
+  }
+
+  #img-title {
+    font-size: 15px;
+    font-weight: 600;
+    color: #eee;
+    line-height: 1.4;
+    margin-bottom: 8px;
+  }
+  .religion-tag {
+    display: inline-block;
+    padding: 3px 12px;
+    border-radius: 10px;
+    font-size: 12px;
+    font-weight: 600;
+    margin-bottom: 12px;
+    color: #fff;
+  }
+  #img-panel img#img-preview { width: 100%; border-radius: 4px; display: block; }
+  .meta-line { font-size: 13px; color: #666; line-height: 1.8; margin-top: 10px; }
+
+  /* ── Feature analysis ── */
+  .section-divider {
+    font-size: 11px;
+    color: #444;
+    text-transform: uppercase;
+    letter-spacing: 1px;
+    border-top: 1px solid #2a2a2a;
+    padding-top: 12px;
+    margin-top: 16px;
+    margin-bottom: 10px;
+  }
+  .feat-row {
+    display: flex;
+    gap: 10px;
+    margin-bottom: 7px;
+    align-items: baseline;
+  }
+  .feat-key {
+    font-size: 11px;
+    color: #555;
+    flex: 0 0 76px;
+    text-transform: uppercase;
+    letter-spacing: .5px;
+  }
+  .feat-val {
+    font-size: 13px;
+    color: #bbb;
+    flex: 1;
+    line-height: 1.4;
+  }
+  .scalars-row {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 6px;
+    margin-top: 10px;
+  }
+  .scalar-chip {
+    background: #222;
+    border: 1px solid #2e2e2e;
+    border-radius: 4px;
+    padding: 3px 8px;
+    font-size: 11px;
+    color: #777;
+  }
+  .scalar-chip b { color: #aaa; font-weight: 500; }
+
+  /* ── Viz thumbnails ── */
+  .viz-row {
+    display: flex;
+    flex-direction: column;
+    gap: 14px;
+    margin-top: 4px;
+  }
+  .viz-thumb-wrap { width: 100%; }
+  .viz-thumb {
+    width: 100%;
+    border-radius: 4px;
+    display: block;
+    background: #111;
+  }
+  .viz-label {
+    font-size: 11px;
+    color: #555;
+    margin-top: 5px;
+    letter-spacing: .3px;
+  }
+
+  .dev-btn {
+    width: 100%;
+    padding: 7px;
+    border-radius: 4px;
+    border: none;
+    font-size: 12px;
+    cursor: pointer;
+    margin-bottom: 6px;
+  }
+  #loading {
+    display: none;
+    position: fixed;
+    bottom: 18px; left: 50%;
+    transform: translateX(-50%);
+    background: rgba(0,0,0,.85);
+    border: 1px solid #333;
+    padding: 8px 20px;
+    border-radius: 20px;
+    font-size: 12px;
+    z-index: 99;
+  }
+</style>
+</head>
+<body>
+
+<div id="img-panel">
+  <div id="panel-header">
+    <h2 data-i18n="panel_overview">Overview</h2>
+    <button id="btn-clear" data-i18n="clear_reset" data-i18n-title="clear_reset_title"
+            title="Reset selection, zoom and panel">Clear / Reset</button>
+  </div>
+
+  <div id="summary-content">
+    <div id="summary-title" data-i18n="summary_all">All points</div>
+    <div id="summary-subtitle"></div>
+    <div class="section-divider" data-i18n="religion_mix">Religion mix</div>
+    <div class="religion-bars" id="summary-religions"></div>
+    <div class="section-divider" data-i18n="description">Description</div>
+    <div id="summary-descriptions"></div>
+    <div class="section-divider" data-i18n="samples">Samples</div>
+    <div class="sample-grid" id="summary-samples"></div>
+  </div>
+
+  <div id="img-empty" data-i18n="click_hint">Click a point in the plot to see its image here.</div>
+  <div id="img-content">
+    <!-- 1. Title -->
+    <div id="img-title"></div>
+    <!-- 2. Religion tag -->
+    <div><span class="religion-tag" id="img-tag"></span></div>
+    <!-- 3. Big image -->
+    <img id="img-preview" src="" alt="">
+    <!-- 4. Artist · year · source -->
+    <div class="meta-line" id="img-meta"></div>
+
+    <!-- 5. Analysis -->
+    <div class="section-divider" data-i18n="analysis">Analysis</div>
+    <div id="feat-rows"></div>
+    <div id="scalars-row" class="scalars-row"></div>
+
+    <!-- 6. Visualizations (smaller) -->
+    <div class="section-divider" data-i18n="visualizations">Visualizations</div>
+    <div class="viz-row" id="viz-row">
+      <div class="viz-thumb-wrap" id="viz-canny-wrap">
+        <img class="viz-thumb" id="viz-canny" src="" alt="Canny">
+        <div class="viz-label" data-i18n="edges">Edges</div>
+      </div>
+      <div class="viz-thumb-wrap" id="viz-faces-wrap" style="display:none">
+        <img class="viz-thumb" id="viz-faces" src="" alt="Faces">
+        <div class="viz-label" data-i18n="faces">Faces</div>
+      </div>
+      <div class="viz-thumb-wrap" id="viz-pose-wrap" style="display:none">
+        <img class="viz-thumb" id="viz-pose" src="" alt="Pose">
+        <div class="viz-label" data-i18n="pose">Pose</div>
+      </div>
+    </div>
+  </div>
+
+  <div id="cluster-content">
+    <div id="cluster-title"></div>
+    <div id="cluster-subtitle"></div>
+    <div class="section-divider" data-i18n="religion_mix">Religion mix</div>
+    <div class="religion-bars" id="cluster-religions"></div>
+    <div class="section-divider" data-i18n="description">Description</div>
+    <div id="cluster-descriptions"></div>
+    <div class="section-divider" data-i18n="samples">Samples</div>
+    <div class="sample-grid" id="cluster-samples"></div>
+  </div>
+</div>
+
+<div id="plot-wrap"></div>
+
+<div id="sidebar">
+  <div id="sidebar-header">
+    <h1 data-i18n="app_title">Religious Art Space</h1>
+    <div id="lang-toggle">
+      <button class="lang-btn active" data-lang="en">EN</button>
+      <button class="lang-btn"        data-lang="sl">SL</button>
+    </div>
+  </div>
+
+  <div>
+    <h2 data-i18n="handcrafted">Hand-crafted</h2>
+    <div class="slider-row">
+      <label><span data-i18n="color_histogram">Color histogram</span><span class="val" id="v-hc_color">1.0</span></label>
+      <input type="range" id="sl-hc_color" min="0" max="2" step="0.1" value="1">
+    </div>
+    <div class="slider-row">
+      <label><span data-i18n="color_flatness">Color flatness</span><span class="val" id="v-hc_flat">1.0</span></label>
+      <input type="range" id="sl-hc_flat" min="0" max="2" step="0.1" value="1">
+    </div>
+    <div class="slider-row">
+      <label><span data-i18n="geometric_patterns">Geometric patterns</span><span class="val" id="v-hc_geom">1.0</span></label>
+      <input type="range" id="sl-hc_geom" min="0" max="2" step="0.1" value="1">
+    </div>
+    <div class="slider-row">
+      <label><span data-i18n="lines">Lines</span><span class="val" id="v-hc_lines">1.0</span></label>
+      <input type="range" id="sl-hc_lines" min="0" max="2" step="0.1" value="1">
+    </div>
+    <div class="slider-row">
+      <label><span data-i18n="light_contrast">Light / contrast</span><span class="val" id="v-hc_light">1.0</span></label>
+      <input type="range" id="sl-hc_light" min="0" max="2" step="0.1" value="1">
+    </div>
+    <div class="slider-row">
+      <label><span data-i18n="symmetry">Symmetry</span><span class="val" id="v-hc_symmetry">1.0</span></label>
+      <input type="range" id="sl-hc_symmetry" min="0" max="2" step="0.1" value="1">
+    </div>
+  </div>
+
+  <div>
+    <h2 data-i18n="learned_other">Learned / other</h2>
+    <div class="slider-row">
+      <label><span>DINOv2</span><span class="val" id="v-dino">1.0</span></label>
+      <input type="range" id="sl-dino" min="0" max="2" step="0.1" value="1">
+    </div>
+    <div class="slider-row">
+      <label><span data-i18n="clip_image">CLIP image</span><span class="val" id="v-clip_v">1.0</span></label>
+      <input type="range" id="sl-clip_v" min="0" max="2" step="0.1" value="1">
+    </div>
+    <div class="slider-row">
+      <label><span data-i18n="clip_attributes">CLIP attributes</span><span class="val" id="v-clip_s">1.0</span></label>
+      <input type="range" id="sl-clip_s" min="0" max="2" step="0.1" value="1">
+    </div>
+    <div class="slider-row">
+      <label><span data-i18n="pose">Pose</span><span class="val" id="v-pose">1.0</span></label>
+      <input type="range" id="sl-pose" min="0" max="2" step="0.1" value="1">
+    </div>
+    <div class="slider-row">
+      <label><span data-i18n="faces">Faces</span><span class="val" id="v-faces">1.0</span></label>
+      <input type="range" id="sl-faces" min="0" max="2" step="0.1" value="1">
+    </div>
+  </div>
+
+  <div>
+    <h2>CLIP Labels</h2>
+    <div class="slider-row">
+      <label><span>Score threshold</span><span class="val" id="v-clip-thr">0.22</span></label>
+      <input type="range" id="sl-clip-thr" min="0.10" max="0.35" step="0.01" value="0.22">
+    </div>
+    <button class="dev-btn" id="btn-edit-labels" onclick="openLabelEditor()"
+      style="width:100%;background:#1a2a1a;border:1px solid #2e7d32;color:#81c784;margin-bottom:6px;">
+      + Edit Labels
+    </button>
+  </div>
+
+  <div style="display:flex; gap:8px;">
+    <button class="dev-btn" id="btn-zero" onclick="toggleAllZero()" style="flex:1;background:#222;border:1px solid #333;color:#aaa;">Set all to 0</button>
+    <button class="dev-btn" id="btn-cluster" onclick="toggleClusters()" style="flex:1;background:#222;border:1px solid #333;color:#aaa;">Clusters</button>
+  </div>
+
+</div>
+
+<!-- CLIP Label Editor Modal -->
+<div id="label-modal" style="display:none;position:fixed;inset:0;z-index:200;
+  background:rgba(0,0,0,.7);align-items:center;justify-content:center;">
+  <div style="background:#181818;border:1px solid #333;border-radius:12px;
+    width:min(680px,94vw);max-height:88vh;display:flex;flex-direction:column;overflow:hidden;">
+
+    <div style="padding:18px 20px 12px;border-bottom:1px solid #2a2a2a;
+      display:flex;align-items:center;justify-content:space-between;">
+      <h2 style="font-size:1rem;font-weight:600;">Edit CLIP Labels</h2>
+      <button onclick="closeLabelEditor()"
+        style="background:none;border:none;color:#666;font-size:1.3rem;cursor:pointer;line-height:1;">×</button>
+    </div>
+
+    <div id="label-editor-body" style="overflow-y:auto;padding:16px 20px;flex:1;"></div>
+
+    <div style="padding:12px 20px;border-top:1px solid #2a2a2a;
+      display:flex;gap:8px;align-items:center;">
+      <button onclick="restoreDefaultLabels()"
+        style="padding:6px 14px;border-radius:6px;border:1px solid #333;
+          background:none;color:#666;cursor:pointer;font-size:.8rem;">
+        ↺ Restore defaults
+      </button>
+      <button onclick="clearAllLabels()"
+        style="padding:6px 14px;border-radius:6px;border:1px solid #333;
+          background:none;color:#666;cursor:pointer;font-size:.8rem;margin-right:auto;">
+        ✕ Clear all
+      </button>
+      <button onclick="closeLabelEditor()"
+        style="padding:7px 18px;border-radius:6px;border:1px solid #333;
+          background:#222;color:#aaa;cursor:pointer;font-size:.85rem;">Cancel</button>
+      <button id="btn-save-labels" onclick="saveLabels()"
+        style="padding:7px 18px;border-radius:6px;border:1px solid #2e7d32;
+          background:#1a2a1a;color:#81c784;cursor:pointer;font-size:.85rem;font-weight:600;">
+        Save &amp; Recompute
+      </button>
+    </div>
+  </div>
+</div>
+
+<div id="loading">⏳ Recomputing t-SNE…</div>
+
+<script>
+const COLORS = {
+  christianity: "#4682b4",
+  islam:        "#55a868",
+  buddhism:     "#c44e52",
+  hinduism:     "#dd8452",
+};
+// Muted versions shown when cluster overlay is active
+const COLORS_MUTED = {
+  christianity: "#4a5e72",
+  islam:        "#4a6354",
+  buddhism:     "#6e4a4b",
+  hinduism:     "#6e5a48",
+};
+
+const SLIDER_IDS = [
+  "hc_color", "hc_flat", "hc_geom", "hc_lines", "hc_light", "hc_symmetry",
+  "dino", "clip_v", "clip_s", "pose", "faces",
+];
+const RELIGION_ORDER = ["christianity", "islam", "buddhism", "hinduism", "general"];
+
+// ── i18n ─────────────────────────────────────────────────────────────────────
+//
+// Static UI strings keyed by `data-i18n` attributes plus dynamic strings
+// looked up via t(). Backend-generated description phrases (e.g. "warm
+// reds/oranges · vibrant") are translated by translateContent() — it splits
+// on " · " and pattern-matches each part against BACKEND_SL.
+
+const I18N = {
+  en: {
+    app_title: "Religious Art Space",
+    panel_overview: "Overview",
+    clear_reset: "Clear / Reset",
+    clear_reset_title: "Reset selection, zoom and panel",
+    summary_all: "All points",
+    religion_mix: "Religion mix",
+    description: "Description",
+    samples: "Samples",
+    analysis: "Analysis",
+    visualizations: "Visualizations",
+    edges: "Edges",
+    faces: "Faces",
+    pose: "Pose",
+    click_hint: "Click a point in the plot to see its image here.",
+    handcrafted: "Hand-crafted",
+    learned_other: "Learned / other",
+    color_histogram: "Color histogram",
+    color_flatness: "Color flatness",
+    geometric_patterns: "Geometric patterns",
+    lines: "Lines",
+    light_contrast: "Light / contrast",
+    symmetry: "Symmetry",
+    clip_image: "CLIP image",
+    clip_attributes: "CLIP attributes",
+    set_all_zero: "Set all to 0",
+    set_all_one: "Set all to 1",
+    clusters_btn: "Clusters",
+    clusters_btn_on: "Clusters ✓",
+    reprojecting: "Reprojecting…",
+    // dynamic helpers
+    images: "images",
+    of: "of",
+    selection: "Selection",
+    zoomed_view: "Zoomed view",
+    cluster: "Cluster",
+    cluster_of: "of",
+    // religion display
+    rel_christianity: "christianity",
+    rel_islam: "islam",
+    rel_buddhism: "buddhism",
+    rel_hinduism: "hinduism",
+  },
+  sl: {
+    app_title: "Prostor verske umetnosti",
+    panel_overview: "Pregled",
+    clear_reset: "Počisti / Ponastavi",
+    clear_reset_title: "Ponastavi izbor, povečavo in panel",
+    summary_all: "Vse točke",
+    religion_mix: "Verska sestava",
+    description: "Opis",
+    samples: "Vzorci",
+    analysis: "Analiza",
+    visualizations: "Vizualizacije",
+    edges: "Robovi",
+    faces: "Obrazi",
+    pose: "Drža",
+    click_hint: "Klikni točko v grafu, da se prikaže slika.",
+    handcrafted: "Ročno izdelane",
+    learned_other: "Naučene / ostalo",
+    color_histogram: "Barvni histogram",
+    color_flatness: "Ploskost barv",
+    geometric_patterns: "Geometrijski vzorci",
+    lines: "Linije",
+    light_contrast: "Svetloba / kontrast",
+    symmetry: "Simetrija",
+    clip_image: "CLIP slika",
+    clip_attributes: "CLIP atributi",
+    set_all_zero: "Vse na 0",
+    set_all_one: "Vse na 1",
+    clusters_btn: "Skupine",
+    clusters_btn_on: "Skupine ✓",
+    reprojecting: "Preračunavanje…",
+    images: "slik",
+    of: "od",
+    selection: "Izbor",
+    zoomed_view: "Povečan pogled",
+    cluster: "Skupina",
+    cluster_of: "od",
+    rel_christianity: "krščanstvo",
+    rel_islam: "islam",
+    rel_buddhism: "budizem",
+    rel_hinduism: "hinduizem",
+  },
+};
+
+// Backend description phrases (full strings the Python labellers emit).
+const BACKEND_SL = {
+  // group headings (shown in feat-key)
+  "Color": "Barva",
+  "Flatness": "Ploskost",
+  "Geometry": "Geometrija",
+  "Lines": "Linije",
+  "Light": "Svetloba",
+  "Symmetry": "Simetrija",
+  "CLIP attr": "CLIP atr.",
+  "Pose": "Drža",
+  "Faces": "Obrazi",
+  // color
+  "warm reds/oranges": "tople rdečo-oranžne",
+  "yellows/greens": "rumeno-zelene",
+  "cool greens/cyans": "hladne zeleno-modre",
+  "blues/purples": "modre/vijolične",
+  "vibrant": "živahno",
+  "muted/desaturated": "umirjeno/nenasičeno",
+  // flatness
+  "flat color fills": "ploskovne barvne ploskve",
+  "painterly gradients": "slikarski prelivi",
+  // geometry
+  "repeating geometric patterns": "ponavljajoči geometrijski vzorci",
+  "complex texture": "kompleksna tekstura",
+  "uniform texture": "enotna tekstura",
+  // lines
+  "strong straight lines": "izrazite ravne linije",
+  "curved/organic lines": "ukrivljene/organske linije",
+  "dominant horizontal lines":  "prevladujoče vodoravne linije",
+  "dominant vertical lines":    "prevladujoče navpične linije",
+  "dominant diagonal↗ lines":   "prevladujoče diagonalne↗ linije",
+  "dominant diagonal↘ lines":   "prevladujoče diagonalne↘ linije",
+  // light
+  "bright": "svetlo",
+  "dark":   "temno",
+  "heavy shadows": "močne sence",
+  "high contrast": "visok kontrast",
+  "low contrast":  "nizek kontrast",
+  // symmetry
+  "left-right symmetric": "levo-desno simetrično",
+  "top-bottom symmetric": "zgoraj-spodaj simetrično",
+  "asymmetric":           "asimetrično",
+  // pose
+  "figurative (bodies present)": "figuralno (s telesi)",
+  "non-figurative": "nefiguralno",
+  // faces
+  "crowd/group scenes": "množične/skupinske scene",
+  "portrait/close-up":  "portret / od blizu",
+  "no faces":           "brez obrazov",
+  // scalar chip labels (long names)
+  "Brightness": "Svetlost",
+  "Contrast":   "Kontrast",
+  "Darkness":   "Temnost",
+  "Edge density":   "Gostota robov",
+  "Avg hue":        "Povp. odtenek",
+  "Avg saturation": "Povp. nasičenost",
+  "Straight ratio": "Razmerje ravnih",
+  "Hough lines":    "Hough linije",
+  "Face coverage":  "Pokritost obraza",
+  "Pose detected":  "Drža zaznana",
+  // CLIP labels
+  "halo": "avreola", "cross": "križ", "virgin mary": "Devica Marija",
+  "angels": "angeli", "nativity": "rojstvo", "biblical figures": "svetopisemske osebe",
+  "calligraphy": "kaligrafija", "arabesque": "arabeska", "mosque": "mošeja",
+  "quran ms": "korana", "islamic tiles": "islamske ploščice",
+  "buddha": "Buda", "lotus": "lotos", "thangka": "thangka",
+  "mandala": "mandala", "dharma wheel": "kolo dharme", "bodhisattva": "bodisatva",
+  "many-armed deity": "večroko božanstvo", "ganesha": "Ganeš",
+  "hindu temple": "hindujski tempelj", "krishna": "Krišna",
+  "shiva nataraja": "Šiva Nataradža", "gold leaf": "zlat list",
+  "prayer": "molitev", "sacred geometry": "sveta geometrija",
+  "ritual objects": "obredni predmeti", "manuscript": "rokopis",
+};
+
+let LANG = localStorage.getItem("lang") || "en";
+
+function t(key) {
+  return (I18N[LANG] && I18N[LANG][key]) || I18N.en[key] || key;
+}
+
+function translatePhrase(s) {
+  if (LANG === "en" || !s) return s;
+  if (BACKEND_SL[s]) return BACKEND_SL[s];
+  // "predominantly <religion>" → "pretežno <religion-sl>"
+  const m = s.match(/^predominantly (.+)$/);
+  if (m) {
+    const rel = m[1].trim();
+    return "pretežno " + (t("rel_" + rel) || rel);
+  }
+  return s;
+}
+
+function translateContent(s) {
+  // Backend joins multi-clause descriptions with " · ".
+  if (LANG === "en" || !s) return s;
+  return s.split(" · ").map(translatePhrase).join(" · ");
+}
+
+function translateReligion(rel) {
+  return t("rel_" + rel) || rel;
+}
+
+function applyI18n() {
+  document.querySelectorAll("[data-i18n]").forEach(el => {
+    el.textContent = t(el.dataset.i18n);
+  });
+  document.querySelectorAll("[data-i18n-title]").forEach(el => {
+    el.title = t(el.dataset.i18nTitle);
+  });
+  // Buttons whose label depends on toggle state
+  document.getElementById("btn-zero").textContent =
+    allZeroed ? t("set_all_one") : t("set_all_zero");
+  document.getElementById("btn-cluster").textContent =
+    showClusters ? t("clusters_btn_on") : t("clusters_btn");
+  // Lang-toggle button active state
+  document.querySelectorAll(".lang-btn").forEach(b => {
+    b.classList.toggle("active", b.dataset.lang === LANG);
+  });
+}
+
+function setLanguage(lang) {
+  if (lang === LANG) return;
+  LANG = lang;
+  localStorage.setItem("lang", lang);
+  applyI18n();
+  // Repaint anything generated from data, not from data-i18n attributes.
+  renderPlot();
+  if (selectedClusterId != null && clusters[selectedClusterId]) {
+    showClusterInfo(selectedClusterId);
+  } else if (document.body.classList.contains("has-image")) {
+    // Best-effort: re-render the current image panel by matching the title.
+    const cur = document.getElementById("img-title").textContent;
+    const p = points.find(pt => (pt.title || pt.filename) === cur);
+    if (p) showInfo(p);
+  } else {
+    showSummary(selectedIndices, selectedIndices ? null : t("summary_all"));
+  }
+}
+document.querySelectorAll(".lang-btn").forEach(b => {
+  b.addEventListener("click", () => setLanguage(b.dataset.lang));
+});
+
+let points       = [];
+let showClusters = false;
+let clusters     = [];
+let pointLabels  = [];        // per-point cluster id, -1 = noise
+let selectedClusterId = null;
+let selectedIndices   = null; // lasso/box selection (null = none)
+
+// ── Plot ──────────────────────────────────────────────────────────────────────
+
+
+function buildTraces(pts) {
+  const palette  = showClusters ? COLORS_MUTED : COLORS;
+  const opacity  = showClusters ? 0.38 : 0.75;
+  const religions = [...new Set(pts.map(p => p.religion))].sort();
+  return religions.map(rel => {
+    const sub = pts.map((p, i) => ({ p, i })).filter(({ p }) => p.religion === rel);
+    // In cluster mode each point's click routes to its cluster; noise (-1)
+    // points get customdata = null, so the click handler ignores them.
+    const customdata = showClusters
+      ? sub.map(({ i }) => {
+          const cid = pointLabels[i];
+          return cid >= 0 ? ["cluster", cid] : null;
+        })
+      : sub.map(({ i }) => i);
+    const text = showClusters
+      ? sub.map(({ i }) => {
+          const cid = pointLabels[i];
+          if (cid < 0 || !clusters[cid]) return "";
+          return `${clusters[cid].label}<br>${clusters[cid].size} images`;
+        })
+      : undefined;
+    return {
+      x:          sub.map(({ p }) => p.x),
+      y:          sub.map(({ p }) => p.y),
+      customdata,
+      text,
+      hoverinfo:  showClusters ? "text" : undefined,
+      mode:       "markers",
+      type:       "scattergl",
+      name:       translateReligion(rel),
+      marker: { color: palette[rel] || "#666", size: 5, opacity },
+    };
+  });
+}
+
+const HULL_PALETTE = [
+  [255,200,100],[100,180,255],[200,100,255],[80,220,160],
+  [255,110,140],[140,230,80],[255,155,60], [60,160,255],
+  [210,60,200], [60,210,160],[255,60,110], [200,210,60],
+];
+
+function buildHullTraces(clusts) {
+  const traces = [];
+  clusts.forEach((c, i) => {
+    const [r,g,b] = HULL_PALETTE[i % HULL_PALETTE.length];
+    const selected = (i === selectedClusterId);
+    // 1) filled outline — visual only (Plotly doesn't fire clicks on the fill)
+    traces.push({
+      x: c.hull.map(p => p[0]),
+      y: c.hull.map(p => p[1]),
+      fill: "toself",
+      fillcolor: `rgba(${r},${g},${b},${selected ? 0.38 : 0.22})`,
+      line: { color: `rgba(${r},${g},${b},${selected ? 1.0 : 0.82})`,
+              width: selected ? 2.5 : 1.5 },
+      mode: "lines",
+      type: "scatter",
+      showlegend: false,
+      hoverinfo: "skip",
+    });
+    // 2) invisible large centroid marker — the actual click target.
+    //    Carries customdata so the click handler can route to the right cluster.
+    traces.push({
+      x: [c.cx],
+      y: [c.cy],
+      customdata: [["cluster", i]],
+      mode: "markers",
+      type: "scatter",
+      marker: { size: 40, color: `rgba(${r},${g},${b},0.001)` },
+      showlegend: false,
+      hoverinfo: "text",
+      text: `${c.label}<br>${c.size} images`,
+      hoverlabel: { bgcolor: "#000", bordercolor: "#555", font: { color: "#eee" } },
+    });
+  });
+  return traces;
+}
+
+function buildAnnotations() {
+  return clusters.map(c => ({
+    x: c.cx, y: c.cy, text: c.label,
+    showarrow: false,
+    font: { color: "#fff", size: 11 },
+    bgcolor: "rgba(0,0,0,0.75)",
+    bordercolor: "#555",
+    borderwidth: 1,
+    borderpad: 4,
+  }));
+}
+
+function renderPlot() {
+  const traces = [
+    ...(showClusters ? buildHullTraces(clusters) : []),
+    ...buildTraces(points),
+  ];
+  const layout = {
+    paper_bgcolor: "#111",
+    plot_bgcolor:  "#111",
+    font:          { color: "#ccc" },
+    xaxis:         { visible: false, zeroline: false },
+    yaxis:         { visible: false, zeroline: false },
+    margin:        { t: 10, b: 10, l: 10, r: 10 },
+    legend: {
+      x: 0, y: 1, xanchor: "left", yanchor: "top",
+      bgcolor: "rgba(0,0,0,0)", font: { size: 12 },
+    },
+    hovermode:     "closest",
+    dragmode:      "zoom",
+    annotations:   showClusters ? buildAnnotations() : [],
+  };
+  Plotly.react("plot-wrap", traces, layout, { responsive: true });
+
+  const el = document.getElementById("plot-wrap");
+
+  el.on("plotly_click", e => {
+    const cd = e.points[0].customdata;
+    if (Array.isArray(cd) && cd[0] === "cluster") {
+      showClusterInfo(cd[1]);
+    } else if (!showClusters && typeof cd === "number") {
+      // Image-point clicks only work outside cluster mode.
+      showInfo(points[cd]);
+    }
+  });
+
+  // Lasso / box-select → summarize selection, then drop the tool. We defer
+  // the dragmode reset to the next tick so it lands AFTER Plotly finishes
+  // its own internal post-selection housekeeping (otherwise it gets ignored).
+  el.on("plotly_selected", e => {
+    const dropTool = () => setTimeout(() => {
+      Plotly.relayout("plot-wrap", { dragmode: "zoom" });
+    }, 0);
+
+    if (!e || !e.points || e.points.length === 0) {
+      showSummaryForAll();
+      dropTool();
+      return;
+    }
+    const idx = [];
+    e.points.forEach(p => {
+      const cd = p.customdata;
+      if (typeof cd === "number") idx.push(cd);
+      // cluster centroid markers (customdata = ["cluster", i]) are ignored.
+    });
+    if (idx.length === 0) { showSummaryForAll(); dropTool(); return; }
+    selectedIndices = idx;
+    showSummary(idx, `${t("selection")} (${idx.length})`);
+    dropTool();
+  });
+
+  // Zoom → summarize what's in view (debounced).
+  el.on("plotly_relayout", e => {
+    if (!e) return;
+    // Ignore pure dragmode changes (no axis info), and selection-frame resets.
+    const touchesAxes =
+      "xaxis.range[0]" in e || "yaxis.range[0]" in e ||
+      "xaxis.autorange" in e || "yaxis.autorange" in e;
+    if (!touchesAxes) return;
+    scheduleZoomSummary();
+  });
+
+  // Cursor feedback: pointer when hovering anything clickable. Plotly stamps
+  // its own crosshair on .nsewdrag, so we toggle a class and override via CSS.
+  el.on("plotly_hover", e => {
+    const cd = e.points[0].customdata;
+    const clickable =
+      (Array.isArray(cd) && cd[0] === "cluster") ||
+      (!showClusters && typeof cd === "number");
+    el.classList.toggle("clickable", clickable);
+  });
+  el.on("plotly_unhover", () => { el.classList.remove("clickable"); });
+}
+
+// ── Info panel ────────────────────────────────────────────────────────────────
+
+async function showInfo(p) {
+  document.body.classList.remove("has-cluster");
+  document.body.classList.add("has-image");
+  selectedClusterId = null;
+
+  // 1. Title
+  document.getElementById("img-title").textContent = p.title || p.filename;
+
+  // 2. Religion tag
+  const tag = document.getElementById("img-tag");
+  tag.textContent      = translateReligion(p.religion);
+  tag.style.background = COLORS[p.religion] || "#555";
+
+  // 3. Image
+  document.getElementById("img-preview").src = `/images/${p.filename}`;
+
+  // 4. Artist · year · source (no title here)
+  document.getElementById("img-meta").innerHTML = [
+    p.artist || "",
+    p.year   || "",
+    p.source ? `<span style="color:#444">${p.source}</span>` : "",
+  ].filter(Boolean).join(" · ");
+
+  // 6a. Canny (always)
+  document.getElementById("viz-canny").src = `/api/viz/canny/${p.filename}`;
+
+  // 6b. Faces (show only if model detects faces)
+  const facesWrap = document.getElementById("viz-faces-wrap");
+  const facesImg  = document.getElementById("viz-faces");
+  facesWrap.style.display = "none";
+  facesImg.onload  = () => { facesWrap.style.display = "block"; };
+  facesImg.onerror = () => { facesWrap.style.display = "none"; };
+  facesImg.src = `/api/viz/faces/${p.filename}`;
+
+  // 6c. Pose (show only if skeleton detected)
+  const poseWrap = document.getElementById("viz-pose-wrap");
+  const poseImg  = document.getElementById("viz-pose");
+  poseWrap.style.display = "none";
+  poseImg.onload  = () => { poseWrap.style.display = "block"; };
+  poseImg.onerror = () => { poseWrap.style.display = "none"; };
+  poseImg.src = `/api/viz/pose/${p.filename}`;
+
+  // 5. Feature descriptions
+  const infoRes  = await fetch(`/api/image_info/${p.filename}`);
+  const info     = await infoRes.json();
+
+  const featRows = document.getElementById("feat-rows");
+  featRows.innerHTML = "";
+  (info.descriptions || []).forEach(d => {
+    const row = document.createElement("div");
+    row.className = "feat-row";
+    const key = translatePhrase(d.group);
+    const val = translateContent(d.label);
+    row.innerHTML = `<span class="feat-key">${key}</span><span class="feat-val">${val}</span>`;
+    featRows.appendChild(row);
+  });
+
+  const scalarsRow = document.getElementById("scalars-row");
+  scalarsRow.innerHTML = "";
+  const scalarLabels = {
+    "Brightness":    "bright",
+    "Contrast":      "contrast",
+    "Darkness":      "dark",
+    "Edge density":  "edges",
+    "Avg hue":       "hue",
+    "Avg saturation":"sat",
+    "Straight ratio":"straight",
+    "Hough lines":   "lines",
+    "Faces":         "faces",
+    "Face coverage": "cov",
+    "Pose detected": "pose",
+  };
+  Object.entries(info.scalars || {}).forEach(([name, val]) => {
+    const chip = document.createElement("span");
+    chip.className = "scalar-chip";
+    const short = scalarLabels[name] || name;
+    const display = Number.isInteger(val) ? val : val.toFixed(2);
+    chip.innerHTML = `<b>${short}</b> ${display}`;
+    scalarsRow.appendChild(chip);
+  });
+}
+
+function showClusterInfo(id) {
+  const c = clusters[id];
+  if (!c) return;
+  selectedClusterId = id;
+  document.body.classList.remove("has-image");
+  document.body.classList.add("has-cluster");
+
+  document.getElementById("cluster-title").textContent =
+    c.label && c.label !== "cluster"
+      ? translateContent(c.label)
+      : `${t("cluster")} ${id + 1}`;
+  document.getElementById("cluster-subtitle").textContent =
+    `${c.size} ${t("images")} · ${t("cluster").toLowerCase()} ${id + 1} ${t("cluster_of")} ${clusters.length}`;
+
+  // Religion mix bars
+  const relWrap = document.getElementById("cluster-religions");
+  relWrap.innerHTML = "";
+  const total = Object.values(c.religion_counts || {}).reduce((a, b) => a + b, 0);
+  Object.entries(c.religion_counts || {})
+    .sort((a, b) => b[1] - a[1])
+    .forEach(([rel, cnt]) => {
+      const pct = total ? (cnt / total) * 100 : 0;
+      const color = COLORS[rel] || "#666";
+      const row = document.createElement("div");
+      row.className = "religion-bar";
+      row.innerHTML = `
+        <span class="rname">${translateReligion(rel)}</span>
+        <span class="rtrack"><span class="rfill" style="width:${pct.toFixed(1)}%;background:${color}"></span></span>
+        <span class="rpct">${pct.toFixed(0)}%</span>`;
+      relWrap.appendChild(row);
+    });
+
+  // Per-group descriptions
+  const descWrap = document.getElementById("cluster-descriptions");
+  descWrap.innerHTML = "";
+  (c.descriptions || []).forEach(d => {
+    const row = document.createElement("div");
+    row.className = "feat-row";
+    const key = translatePhrase(d.group);
+    const val = translateContent(d.label);
+    row.innerHTML = `<span class="feat-key">${key}</span><span class="feat-val">${val}</span>`;
+    descWrap.appendChild(row);
+  });
+
+  // Sample thumbnails — click loads that image's full panel
+  const sampWrap = document.getElementById("cluster-samples");
+  sampWrap.innerHTML = "";
+  (c.samples || []).forEach(fn => {
+    const img = document.createElement("img");
+    img.src = `/images/${fn}`;
+    img.title = fn;
+    img.onclick = () => {
+      const p = points.find(pt => pt.filename === fn);
+      if (p) showInfo(p);
+    };
+    sampWrap.appendChild(img);
+  });
+
+  // Re-render so the selected hull gets its highlight styling.
+  renderPlot();
+}
+
+// ── Summary panel (overview / lasso / zoom) ──────────────────────────────────
+
+async function showSummary(indices, title) {
+  // Switch to summary state — image/cluster panels hide.
+  document.body.classList.remove("has-image");
+  document.body.classList.remove("has-cluster");
+  selectedClusterId = null;
+
+  const res  = await fetch("/api/subset_info", {
+    method:  "POST",
+    headers: { "Content-Type": "application/json" },
+    body:    JSON.stringify({ indices: indices || null }),
+  });
+  const data = await res.json();
+
+  document.getElementById("summary-title").textContent = title || t("summary_all");
+  const sub = data.total && data.count !== data.total
+    ? `${data.count} ${t("of")} ${data.total} ${t("images")}`
+    : `${data.count} ${t("images")}`;
+  document.getElementById("summary-subtitle").textContent = sub;
+
+  // Religion mix bars
+  const relWrap = document.getElementById("summary-religions");
+  relWrap.innerHTML = "";
+  const total = Object.values(data.religion_counts || {}).reduce((a, b) => a + b, 0);
+  Object.entries(data.religion_counts || {})
+    .sort((a, b) => b[1] - a[1])
+    .forEach(([rel, cnt]) => {
+      const pct = total ? (cnt / total) * 100 : 0;
+      const color = COLORS[rel] || "#666";
+      const row = document.createElement("div");
+      row.className = "religion-bar";
+      row.innerHTML = `
+        <span class="rname">${translateReligion(rel)}</span>
+        <span class="rtrack"><span class="rfill" style="width:${pct.toFixed(1)}%;background:${color}"></span></span>
+        <span class="rpct">${pct.toFixed(0)}%</span>`;
+      relWrap.appendChild(row);
+    });
+
+  // Descriptions
+  const descWrap = document.getElementById("summary-descriptions");
+  descWrap.innerHTML = "";
+  (data.descriptions || []).forEach(d => {
+    const row = document.createElement("div");
+    row.className = "feat-row";
+    const key = translatePhrase(d.group);
+    const val = translateContent(d.label);
+    row.innerHTML = `<span class="feat-key">${key}</span><span class="feat-val">${val}</span>`;
+    descWrap.appendChild(row);
+  });
+
+  // Samples
+  const sampWrap = document.getElementById("summary-samples");
+  sampWrap.innerHTML = "";
+  (data.samples || []).forEach(fn => {
+    const img = document.createElement("img");
+    img.src = `/images/${fn}`;
+    img.title = fn;
+    img.onclick = () => {
+      const p = points.find(pt => pt.filename === fn);
+      if (p) showInfo(p);
+    };
+    sampWrap.appendChild(img);
+  });
+}
+
+function showSummaryForAll() {
+  selectedIndices = null;
+  showSummary(null, "All points");
+}
+
+// Debounced zoom-summary: filter currently-visible points and summarize them.
+let zoomTimer = null;
+function scheduleZoomSummary() {
+  clearTimeout(zoomTimer);
+  zoomTimer = setTimeout(computeZoomSummary, 250);
+}
+function computeZoomSummary() {
+  const el = document.getElementById("plot-wrap");
+  const fl = el._fullLayout;
+  if (!fl || !fl.xaxis || !fl.yaxis) return;
+  const xr = fl.xaxis.range, yr = fl.yaxis.range;
+  if (!xr || !yr) return;
+  // Detect "fully zoomed out" → treat as overview.
+  const xspan = xr[1] - xr[0], yspan = yr[1] - yr[0];
+  let allMinX = Infinity, allMaxX = -Infinity, allMinY = Infinity, allMaxY = -Infinity;
+  for (const p of points) {
+    if (p.x < allMinX) allMinX = p.x;
+    if (p.x > allMaxX) allMaxX = p.x;
+    if (p.y < allMinY) allMinY = p.y;
+    if (p.y > allMaxY) allMaxY = p.y;
+  }
+  const isFullView =
+    xr[0] <= allMinX - 0.001 && xr[1] >= allMaxX + 0.001 &&
+    yr[0] <= allMinY - 0.001 && yr[1] >= allMaxY + 0.001;
+  if (isFullView) { showSummaryForAll(); return; }
+
+  const idx = [];
+  for (let i = 0; i < points.length; i++) {
+    const p = points[i];
+    if (p.x >= xr[0] && p.x <= xr[1] && p.y >= yr[0] && p.y <= yr[1]) idx.push(i);
+  }
+  if (idx.length === 0) { showSummaryForAll(); return; }
+  selectedIndices = idx;
+  showSummary(idx, `${t("zoomed_view")} (${idx.length})`);
+}
+
+document.getElementById("btn-clear").onclick = () => {
+  // Full reset — same state as a fresh page load.
+  selectedIndices   = null;
+  selectedClusterId = null;
+  // Drop any selection highlight on every trace.
+  Plotly.restyle("plot-wrap", "selectedpoints", null);
+  // Reset zoom, dragmode, and clear Plotly v2's persistent selection outline.
+  Plotly.relayout("plot-wrap", {
+    "xaxis.autorange": true,
+    "yaxis.autorange": true,
+    dragmode: "zoom",
+    selections: [],
+  });
+  showSummaryForAll();
+};
+
+// ── Init ──────────────────────────────────────────────────────────────────────
+
+async function init() {
+  applyI18n();
+  const [embRes, thrRes] = await Promise.all([
+    fetch("/api/embeddings"),
+    fetch("/api/clip_threshold"),
+  ]);
+  points = await embRes.json();
+  const { threshold } = await thrRes.json();
+  const sl = document.getElementById("sl-clip-thr");
+  sl.value = threshold;
+  document.getElementById("v-clip-thr").textContent = threshold.toFixed(2);
+  renderPlot();
+  showSummaryForAll();
+}
+
+// ── Sliders / Reproject ───────────────────────────────────────────────────────
+
+function weights() {
+  const w = {};
+  SLIDER_IDS.forEach(k => { w[k] = +document.getElementById("sl-" + k).value; });
+  return w;
+}
+
+let timer = null;
+function onSlider() {
+  const w = weights();
+  SLIDER_IDS.forEach(k => {
+    document.getElementById("v-" + k).textContent = w[k].toFixed(1);
+  });
+  clearTimeout(timer);
+  timer = setTimeout(() => reproject(w), 800);
+}
+
+async function reproject(w) {
+  document.getElementById("loading").style.display = "flex";
+  try {
+    const res    = await fetch("/api/reproject", {
+      method:  "POST",
+      headers: { "Content-Type": "application/json" },
+      body:    JSON.stringify(w),
+    });
+    const coords = await res.json();
+    coords.forEach((c, i) => { points[i].x = c.x; points[i].y = c.y; });
+    clusters = []; pointLabels = []; selectedClusterId = null;
+    document.body.classList.remove("has-cluster");
+    renderPlot();
+  } finally {
+    document.getElementById("loading").style.display = "none";
+  }
+}
+
+let allZeroed = false;
+function toggleAllZero() {
+  allZeroed = !allZeroed;
+  const val = allZeroed ? 0 : 1;
+  SLIDER_IDS.forEach(k => {
+    document.getElementById("sl-" + k).value = val;
+    document.getElementById("v-" + k).textContent = val.toFixed(1);
+  });
+  const btn = document.getElementById("btn-zero");
+  btn.textContent = allZeroed ? t("set_all_one") : t("set_all_zero");
+  reproject(weights());
+}
+
+SLIDER_IDS.forEach(k =>
+  document.getElementById("sl-" + k).addEventListener("input", onSlider)
+);
+
+// ── CLIP Score Threshold slider ───────────────────────────────────────────────
+
+let clipThrTimer = null;
+document.getElementById("sl-clip-thr").addEventListener("input", () => {
+  const v = +document.getElementById("sl-clip-thr").value;
+  document.getElementById("v-clip-thr").textContent = v.toFixed(2);
+  clearTimeout(clipThrTimer);
+  clipThrTimer = setTimeout(async () => {
+    document.getElementById("loading").style.display = "flex";
+    try {
+      const res  = await fetch("/api/clip_threshold", {
+        method: "POST",
+        headers: {"Content-Type": "application/json"},
+        body: JSON.stringify({threshold: v}),
+      });
+      const data = await res.json();
+      if (data.points) {
+        data.points.forEach((c, i) => { if (points[i]) { points[i].x = c.x; points[i].y = c.y; } });
+        clusters = []; pointLabels = []; selectedClusterId = null;
+        renderPlot();
+        Plotly.relayout("plot-wrap", {"xaxis.autorange": true, "yaxis.autorange": true});
+      }
+    } finally {
+      document.getElementById("loading").style.display = "none";
+    }
+  }, 800);
+});
+
+// ── CLIP Label Editor ─────────────────────────────────────────────────────────
+
+const DEFAULT_CLIP_LABELS = {
+  christianity: [
+    {label:"halo",          prompt:"a golden halo around a figure"},
+    {label:"cross",         prompt:"a crucifix or cross"},
+    {label:"virgin mary",   prompt:"the virgin mary"},
+    {label:"angels",        prompt:"angels with wings"},
+    {label:"nativity",      prompt:"a nativity scene"},
+    {label:"biblical figs", prompt:"biblical figures in robes"},
+  ],
+  islam: [
+    {label:"calligraphy",   prompt:"arabic calligraphy"},
+    {label:"arabesque",     prompt:"geometric arabesque patterns"},
+    {label:"mosque",        prompt:"a mosque with a minaret"},
+    {label:"quran ms",      prompt:"an illuminated quran manuscript"},
+    {label:"islamic tiles", prompt:"islamic tile patterns"},
+  ],
+  buddhism: [
+    {label:"buddha",        prompt:"a buddha statue"},
+    {label:"lotus",         prompt:"a lotus flower"},
+    {label:"thangka",       prompt:"a thangka painting"},
+    {label:"mandala",       prompt:"a mandala"},
+    {label:"dharma wheel",  prompt:"a dharma wheel"},
+    {label:"bodhisattva",   prompt:"a bodhisattva figure"},
+  ],
+  hinduism: [
+    {label:"many-armed",    prompt:"a deity with multiple arms"},
+    {label:"ganesha",       prompt:"ganesha the elephant god"},
+    {label:"hindu temple",  prompt:"a colorful hindu temple"},
+    {label:"krishna",       prompt:"krishna playing the flute"},
+    {label:"shiva nataraja",prompt:"dancing shiva nataraja"},
+  ],
+  general: [
+    {label:"gold leaf",     prompt:"gold leaf background"},
+    {label:"prayer",        prompt:"religious figures in prayer"},
+    {label:"sacred geom.",  prompt:"sacred geometry"},
+    {label:"ritual objects",prompt:"incense and ritual objects"},
+    {label:"manuscript",    prompt:"a religious manuscript"},
+  ],
+};
+
+let labelEditorState = {};  // religion → [{label, prompt}, ...]
+
+function restoreDefaultLabels() {
+  labelEditorState = JSON.parse(JSON.stringify(DEFAULT_CLIP_LABELS));
+  renderLabelEditor();
+}
+
+function clearAllLabels() {
+  RELIGION_ORDER.forEach(rel => { labelEditorState[rel] = []; });
+  renderLabelEditor();
+}
+
+async function openLabelEditor() {
+  const res  = await fetch("/api/clip_labels");
+  labelEditorState = await res.json();
+  renderLabelEditor();
+  document.getElementById("label-modal").style.display = "flex";
+}
+
+function closeLabelEditor() {
+  document.getElementById("label-modal").style.display = "none";
+}
+
+const RELIGION_DISPLAY = {
+  christianity: "Christianity", islam: "Islam",
+  buddhism: "Buddhism", hinduism: "Hinduism", general: "General",
+};
+
+function renderLabelEditor() {
+  const body = document.getElementById("label-editor-body");
+  body.innerHTML = "";
+
+  RELIGION_ORDER.forEach(rel => {
+    const entries = labelEditorState[rel] || [];
+    const sec = document.createElement("div");
+    sec.style.cssText = "margin-bottom:18px;";
+
+    const heading = document.createElement("div");
+    heading.style.cssText = "font-size:.75rem;font-weight:700;text-transform:uppercase;letter-spacing:.07em;color:#888;margin-bottom:8px;";
+    heading.textContent = RELIGION_DISPLAY[rel] || rel;
+    sec.appendChild(heading);
+
+    // Tag row
+    const tagRow = document.createElement("div");
+    tagRow.style.cssText = "display:flex;flex-wrap:wrap;gap:6px;margin-bottom:8px;";
+    entries.forEach((e, idx) => {
+      const tag = document.createElement("span");
+      tag.title = e.prompt;
+      tag.style.cssText = "display:inline-flex;align-items:center;gap:4px;padding:3px 8px 3px 10px;" +
+        "background:#252525;border:1px solid #333;border-radius:20px;font-size:.78rem;color:#ccc;";
+      tag.innerHTML = `${e.label} <button onclick="removeLabel('${rel}',${idx})" style="background:none;border:none;color:#666;cursor:pointer;font-size:.9rem;line-height:1;padding:0 2px;" title="Remove">×</button>`;
+      tagRow.appendChild(tag);
+    });
+    sec.appendChild(tagRow);
+
+    // Add row
+    const addRow = document.createElement("div");
+    addRow.style.cssText = "display:flex;gap:6px;";
+    addRow.innerHTML = `
+      <input placeholder="Short label" id="add-label-${rel}"
+        style="flex:1;min-width:80px;background:#111;border:1px solid #333;border-radius:6px;
+          padding:5px 8px;color:#ddd;font-size:.8rem;" />
+      <input placeholder="Full prompt text" id="add-prompt-${rel}"
+        style="flex:2;background:#111;border:1px solid #333;border-radius:6px;
+          padding:5px 8px;color:#ddd;font-size:.8rem;" />
+      <button onclick="addLabel('${rel}')"
+        style="padding:5px 12px;border-radius:6px;border:1px solid #2e7d32;
+          background:#1a2a1a;color:#81c784;cursor:pointer;font-size:.85rem;font-weight:600;">+</button>`;
+    sec.appendChild(addRow);
+
+    // Enter key in either input triggers add
+    ['add-label-', 'add-prompt-'].forEach(prefix => {
+      setTimeout(() => {
+        const el = document.getElementById(prefix + rel);
+        if (el) el.addEventListener('keydown', e => { if (e.key === 'Enter') addLabel(rel); });
+      }, 0);
+    });
+
+    body.appendChild(sec);
+  });
+}
+
+function removeLabel(rel, idx) {
+  labelEditorState[rel].splice(idx, 1);
+  renderLabelEditor();
+}
+
+function addLabel(rel) {
+  const lEl = document.getElementById("add-label-" + rel);
+  const pEl = document.getElementById("add-prompt-" + rel);
+  const label  = lEl.value.trim();
+  const prompt = pEl.value.trim();
+  if (!label || !prompt) { lEl.focus(); return; }
+  if (!labelEditorState[rel]) labelEditorState[rel] = [];
+  labelEditorState[rel].push({ label, prompt });
+  lEl.value = ""; pEl.value = "";
+  renderLabelEditor();
+}
+
+async function saveLabels() {
+  const btn = document.getElementById("btn-save-labels");
+  btn.disabled = true;
+  btn.textContent = "Saving…";
+  try {
+    const res = await fetch("/api/clip_labels", {
+      method:  "POST",
+      headers: { "Content-Type": "application/json" },
+      body:    JSON.stringify(labelEditorState),
+    });
+    const data = await res.json();
+    if (data.points) {
+      data.points.forEach((c, i) => { if (points[i]) { points[i].x = c.x; points[i].y = c.y; } });
+      clusters = []; pointLabels = []; selectedClusterId = null;
+      document.body.classList.remove("has-cluster");
+    }
+    closeLabelEditor();
+    renderPlot();
+    Plotly.relayout("plot-wrap", { "xaxis.autorange": true, "yaxis.autorange": true });
+  } finally {
+    btn.disabled = false;
+    btn.textContent = "Save & Recompute";
+  }
+}
+
+// ── Recompute t-SNE ───────────────────────────────────────────────────────────
+
+async function triggerRecompute() {
+  const btn = document.getElementById("btn-recompute");
+  btn.disabled = true;
+  btn.textContent = "↺ Running…";
+  document.getElementById("loading").style.display = "flex";
+  try {
+    const res  = await fetch("/api/recompute", { method: "POST" });
+    const data = await res.json();
+    data.points.forEach((c, i) => { if (points[i]) { points[i].x = c.x; points[i].y = c.y; } });
+    clusters = []; pointLabels = []; selectedClusterId = null;
+    document.body.classList.remove("has-cluster");
+    renderPlot();
+    Plotly.relayout("plot-wrap", { "xaxis.autorange": true, "yaxis.autorange": true });
+  } finally {
+    btn.disabled = false;
+    btn.textContent = "↺ Recompute t-SNE";
+    document.getElementById("loading").style.display = "none";
+  }
+}
+
+// ── Clusters ──────────────────────────────────────────────────────────────────
+
+async function fetchClusters() {
+  const res = await fetch("/api/cluster", { method: "POST" });
+  const data = await res.json();
+  clusters    = data.clusters || [];
+  pointLabels = data.point_labels || [];
+}
+
+async function toggleClusters() {
+  showClusters = !showClusters;
+  const btn = document.getElementById("btn-cluster");
+  if (showClusters) {
+    btn.textContent       = t("clusters_btn_on");
+    btn.style.background  = "#7c3aed22";
+    btn.style.borderColor = "#7c3aed";
+    btn.style.color       = "#a78bfa";
+    document.getElementById("loading").style.display = "flex";
+    try {
+      await fetchClusters();
+    } finally {
+      document.getElementById("loading").style.display = "none";
+    }
+  } else {
+    btn.textContent       = t("clusters_btn");
+    btn.style.background  = "#222";
+    btn.style.borderColor = "#333";
+    btn.style.color       = "#aaa";
+    clusters = [];
+    pointLabels = [];
+    selectedClusterId = null;
+    document.body.classList.remove("has-cluster");
+  }
+  renderPlot();
+}
+
+init();
+</script>
+</body>
+</html>

data/README.md

@@ -0,0 +1,20 @@
+# Data
+
+Download from Kaggle (needs an API token from https://www.kaggle.com/settings):
+
+    pip install kaggle
+    python data/download.py
+
+Expected layout after download:
+
+    data/artwork_metadata.csv   3,997 rows — filename, religion (1,000 each of
+                                buddhism / christianity / hinduism; 997 islam),
+                                sub_religion, artist, title, year, place,
+                                source, source_id, source_url, image_url
+    data/images/                the 3,997 images, filenames match the CSV
+                                (download.py flattens Kaggle's images/images/)
+
+Generated later by the pipeline (gitignored):
+
+    data/masks/         guarded background masks + verdicts.csv
+    data/features/      one parquet per feature family

data/download.py

@@ -0,0 +1,45 @@
+"""
+Download the Religious Artwork Dataset from Kaggle into data/.
+
+Requires the Kaggle API (pip install kaggle) and either ~/.kaggle/kaggle.json
+or the KAGGLE_API_TOKEN environment variable
+(create a token at https://www.kaggle.com/settings).
+
+Usage: python data/download.py
+"""
+
+import shutil
+import subprocess
+import sys
+import zipfile
+from pathlib import Path
+
+DATASET = "zigaklun/religious-artwork-dataset"
+DATA = Path(__file__).resolve().parent
+
+
+def main():
+    zip_path = DATA / "religious-artwork-dataset.zip"
+    if not zip_path.exists():
+        print(f"Downloading {DATASET} (~6 GB) ...")
+        r = subprocess.run(["kaggle", "datasets", "download", "-d", DATASET,
+                            "-p", str(DATA)])
+        if r.returncode != 0:
+            sys.exit("kaggle CLI failed — is your Kaggle API token set up?")
+    print("Unpacking ...")
+    with zipfile.ZipFile(zip_path) as z:
+        z.extractall(DATA)
+
+    # Kaggle nests the image folder: images/images/*.jpg -> flatten to images/
+    nested = DATA / "images" / "images"
+    if nested.is_dir():
+        for f in nested.iterdir():
+            shutil.move(str(f), DATA / "images" / f.name)
+        nested.rmdir()
+
+    n = len(list((DATA / "images").glob("*.jpg")))
+    print(f"Done. data/artwork_metadata.csv + data/images/ ({n} images, expected 3997)")
+
+
+if __name__ == "__main__":
+    main()

evaluation/family_accuracy.py

@@ -0,0 +1,90 @@
+"""
+Religion-classification accuracy per feature family, under two protocols:
+
+  pooled — stratified 5-fold CV: "is there any association at all?"
+  LOSO   — leave-one-source-out: "does it transfer to an unseen museum?"
+
+The gap between the two columns measures source leakage: features that
+encode museum reproduction style (scan texture, framing) score high pooled
+but collapse under LOSO.
+
+Requires all feature parquets in data/features/ (run the extractors first).
+Usage: python evaluation/family_accuracy.py
+"""
+
+import warnings
+
+warnings.filterwarnings("ignore")
+
+import numpy as np
+import pandas as pd
+from sklearn.ensemble import RandomForestClassifier
+from sklearn.linear_model import LogisticRegression
+from sklearn.model_selection import LeaveOneGroupOut, StratifiedKFold, cross_val_score
+from sklearn.pipeline import make_pipeline
+from sklearn.preprocessing import StandardScaler
+
+SELECTED = "data/artwork_metadata.csv"
+FEAT = "data/features"
+
+
+def aligned(order, path, veccol=None, cols_=None):
+    df = pd.read_parquet(path).drop_duplicates("filename")
+    m = order[["filename"]].merge(df, on="filename", how="left")
+    if veccol is not None:
+        dim = len(next(v for v in m[veccol] if v is not None and not isinstance(v, float)))
+        return np.stack([np.asarray(v, float)
+                         if v is not None and not isinstance(v, float)
+                         else np.zeros(dim) for v in m[veccol]])
+    return m[cols_].fillna(0).to_numpy(float)
+
+
+def main():
+    gold = pd.read_csv(SELECTED, dtype=str).drop_duplicates("filename")
+    hc = gold.merge(pd.read_parquet(f"{FEAT}/handcrafted.parquet"), on="filename")
+
+    def cols(*prefs):
+        return [c for c in hc.columns if c.startswith(prefs)]
+
+    FAM = {
+        "hc color": hc[cols("hc_hist_", "hc_norm_hist_", "hc_h_hist_", "hc_s_hist_",
+                            "hc_v_hist_") + ["hc_avg_hue", "hc_avg_sat"]].to_numpy(),
+        "hc light": hc[["hc_brightness", "hc_contrast", "hc_darkness",
+                        "hc_edge_density"]].to_numpy(),
+        "hc symmetry": hc[["hc_sym_lr", "hc_sym_tb"]].to_numpy(),
+        "hc flatness": hc[cols("hc_flatness_")].to_numpy(),
+        "hc texture": hc[cols("hc_fft_band_", "hc_lbp_")].to_numpy(),
+        "hc lines": hc[cols("hc_hough_", "hc_angle_hist_") + ["hc_straight_ratio"]].to_numpy(),
+    }
+    FAM["hc ALL"] = np.hstack(list(FAM.values()))
+    FAM["clip vector"] = aligned(hc, f"{FEAT}/clip.parquet", "clip_vector")
+    FAM["clip scores"] = aligned(hc, f"{FEAT}/clip.parquet", "clip_scores")
+    FAM["dino"] = aligned(hc, f"{FEAT}/dino.parquet", "dino_vector")
+    FAM["faces"] = aligned(hc, f"{FEAT}/faces.parquet", "face_vector")
+    FAM["pose"] = aligned(hc, f"{FEAT}/pose.parquet",
+                          cols_=[f"main_skel_{i}" for i in range(34)]
+                          + ["main_area", "n_persons"])
+
+    y, src = hc["religion"].to_numpy(), hc["source"].to_numpy()
+    cv = StratifiedKFold(5, shuffle=True, random_state=0)
+    logo = LeaveOneGroupOut()
+
+    def model(dim):
+        if dim > 100:
+            return make_pipeline(StandardScaler(), LogisticRegression(max_iter=3000))
+        return RandomForestClassifier(300, random_state=0, n_jobs=-1)
+
+    print(f"{'family':14s} {'dims':>5s} {'pooled':>7s} {'LOSO':>6s}   (chance 0.250)")
+    for name, X in FAM.items():
+        pooled = cross_val_score(model(X.shape[1]), X, y, cv=cv).mean()
+        parts = []
+        for tr, te in logo.split(X, y, src):
+            mdl = model(X.shape[1])
+            mdl.fit(X[tr], y[tr])
+            parts.append((len(te), mdl.score(X[te], y[te])))
+        loso = sum(n * s for n, s in parts) / sum(n for n, s in parts)
+        print(f"{name:14s} {X.shape[1]:5d} {pooled:7.3f} {loso:6.3f}")
+
+
+if __name__ == "__main__":
+    main()

features/README.md

@@ -0,0 +1,22 @@
+# Feature extractors
+
+One script per family. All read `data/artwork_metadata.csv` + `data/images/`, write to
+`data/features/`, checkpoint regularly, and resume if re-run.
+
+| family       | script                    | dims | what it measures |
+|--------------|---------------------------|-----:|------------------|
+| hand-crafted | `extract_handcrafted.py`  |  380 | color (HSV joint + grey-world + per-channel histograms), light (brightness/contrast/darkness/edge density), symmetry, flatness (SLIC superpixel LAB uniformity), texture (FFT radial bands + 59-bin nri-uniform LBP), lines (Hough count/density, straight ratio, edge-angle histogram) |
+| CLIP         | `extract_clip.py`         | 512 + 27 | ViT-B/16 image embedding + zero-shot cosine scores against 27 hand-written religious-attribute prompts |
+| DINOv2       | `extract_dino.py`         |  768 | self-supervised CLS token — visual style/appearance similarity |
+| faces        | `extract_faces.py`        |   39 | YuNet detections summarized: count, coverage, sizes, positions, tilt/frontality, arrangement, spatial histograms |
+| pose         | `extract_pose.py`         |   39 | YOLOv8-pose, **largest figure only**: torso-normalised 17-keypoint skeleton + figure area + detection-quality columns + person count |
+
+Notes:
+
+- Hand-crafted features use the corrected preprocessing pipeline: images are
+  border-cropped, guardedly background-masked (see `preprocessing/`), and
+  capped at 1024 px on the longest side so texture/edge features measure the
+  artwork rather than the museum's scan resolution.
+- The pose vector stores quality indicators (`main_kpt_conf`, `main_torso_px`)
+  because photo-trained detectors are unreliable on stylised bodies — filter
+  on them before interpreting posture.

features/extract_clip.py

@@ -0,0 +1,101 @@
+"""
+CLIP (ViT-B/16) features for every image in data/artwork_metadata.csv.
+
+Two outputs per image:
+  clip_vector — 512-dim L2-normalised image embedding
+  clip_scores — 27 cosine similarities against religious visual attributes
+
+Output: data/features/clip.parquet   (checkpointed, resumable)
+Usage:  python features/extract_clip.py [--batch-size 64]
+"""
+
+import argparse
+from pathlib import Path
+
+import clip
+import numpy as np
+import pandas as pd
+import torch
+from PIL import Image
+from tqdm import tqdm
+
+IMAGES = Path("data/images")
+SELECTED = Path("data/artwork_metadata.csv")
+OUTPUT = Path("data/features/clip.parquet")
+
+ATTRIBUTES = [
+    # Christianity
+    "a golden halo around a figure", "a crucifix or cross", "the virgin mary",
+    "angels with wings", "a nativity scene", "biblical figures in robes",
+    # Islam
+    "arabic calligraphy", "geometric arabesque patterns", "a mosque with a minaret",
+    "an illuminated quran manuscript", "islamic tile patterns",
+    # Buddhism
+    "a buddha statue", "a lotus flower", "a thangka painting", "a mandala",
+    "a dharma wheel", "a bodhisattva figure",
+    # Hinduism
+    "a deity with multiple arms", "ganesha the elephant god", "a colorful hindu temple",
+    "krishna playing the flute", "dancing shiva nataraja",
+    # Cross-religion / general
+    "gold leaf background", "religious figures in prayer", "sacred geometry",
+    "incense and ritual objects", "a religious manuscript",
+]
+
+Image.MAX_IMAGE_PIXELS = None
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--batch-size", type=int, default=64)
+    ap.add_argument("--save-every", type=int, default=10, help="batches between checkpoints")
+    ap.add_argument("--device", default="cuda" if torch.cuda.is_available() else "cpu")
+    args = ap.parse_args()
+
+    OUTPUT.parent.mkdir(parents=True, exist_ok=True)
+    sel = pd.read_csv(SELECTED, dtype=str).drop_duplicates("filename")
+    existing = pd.read_parquet(OUTPUT) if OUTPUT.exists() else pd.DataFrame(columns=["filename"])
+    done = set(existing["filename"])
+    todo = [f for f in sel["filename"] if f not in done]
+    print(f"total={len(sel)}  done={len(done)}  todo={len(todo)}")
+
+    model, preprocess = clip.load("ViT-B/16", device=args.device)
+    model.eval()
+    with torch.no_grad():
+        tokens = clip.tokenize(ATTRIBUTES).to(args.device)
+        text = model.encode_text(tokens).float()
+        text = text / text.norm(dim=-1, keepdim=True)
+
+    rows = existing.to_dict("records")
+    batch, names = [], []
+
+    def flush():
+        nonlocal batch, names
+        if not batch:
+            return
+        with torch.no_grad():
+            imgs = torch.stack(batch).to(args.device)
+            feats = model.encode_image(imgs).float()
+            feats = feats / feats.norm(dim=-1, keepdim=True)
+            scores = (feats @ text.T).cpu().numpy()
+            vecs = feats.cpu().numpy()
+        for fn, v, s in zip(names, vecs, scores):
+            rows.append({"filename": fn, "clip_vector": v.tolist(), "clip_scores": s.tolist()})
+        batch, names = [], []
+
+    for i, fn in enumerate(tqdm(todo)):
+        try:
+            batch.append(preprocess(Image.open(IMAGES / fn).convert("RGB")))
+            names.append(fn)
+        except Exception as e:
+            print(f"FAIL {fn}: {e}")
+        if len(batch) >= args.batch_size:
+            flush()
+            if (i // args.batch_size) % args.save_every == 0:
+                pd.DataFrame(rows).to_parquet(OUTPUT, index=False)
+    flush()
+    pd.DataFrame(rows).to_parquet(OUTPUT, index=False)
+    print(f"Wrote {OUTPUT}: {len(rows)} rows")
+
+
+if __name__ == "__main__":
+    main()

features/extract_dino.py

@@ -0,0 +1,79 @@
+"""
+DINOv2 (dinov2_vitb14) CLS-token features for every image in data/artwork_metadata.csv.
+
+Output: data/features/dino.parquet   (checkpointed, resumable)
+  filename, dino_vector (768 float32)
+
+Usage:  python features/extract_dino.py [--batch-size 32]
+"""
+
+import argparse
+from pathlib import Path
+
+import pandas as pd
+import torch
+from PIL import Image
+from torchvision import transforms
+from tqdm import tqdm
+
+IMAGES = Path("data/images")
+SELECTED = Path("data/artwork_metadata.csv")
+OUTPUT = Path("data/features/dino.parquet")
+
+TRANSFORM = transforms.Compose([
+    transforms.Resize(256),
+    transforms.CenterCrop(224),
+    transforms.ToTensor(),
+    transforms.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]),
+])
+
+Image.MAX_IMAGE_PIXELS = None
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--batch-size", type=int, default=32)
+    ap.add_argument("--save-every", type=int, default=10)
+    ap.add_argument("--device", default="cuda" if torch.cuda.is_available() else "cpu")
+    args = ap.parse_args()
+
+    OUTPUT.parent.mkdir(parents=True, exist_ok=True)
+    sel = pd.read_csv(SELECTED, dtype=str).drop_duplicates("filename")
+    existing = pd.read_parquet(OUTPUT) if OUTPUT.exists() else pd.DataFrame(columns=["filename"])
+    done = set(existing["filename"])
+    todo = [f for f in sel["filename"] if f not in done]
+    print(f"total={len(sel)}  done={len(done)}  todo={len(todo)}")
+
+    model = torch.hub.load("facebookresearch/dinov2", "dinov2_vitb14", verbose=False)
+    model.eval().to(args.device)
+
+    rows = existing.to_dict("records")
+    batch, names = [], []
+
+    def flush():
+        nonlocal batch, names
+        if not batch:
+            return
+        with torch.no_grad():
+            feats = model(torch.stack(batch).to(args.device)).cpu().float().numpy()
+        for fn, v in zip(names, feats):
+            rows.append({"filename": fn, "dino_vector": v.tolist()})
+        batch, names = [], []
+
+    for i, fn in enumerate(tqdm(todo)):
+        try:
+            batch.append(TRANSFORM(Image.open(IMAGES / fn).convert("RGB")))
+            names.append(fn)
+        except Exception as e:
+            print(f"FAIL {fn}: {e}")
+        if len(batch) >= args.batch_size:
+            flush()
+            if (i // args.batch_size) % args.save_every == 0:
+                pd.DataFrame(rows).to_parquet(OUTPUT, index=False)
+    flush()
+    pd.DataFrame(rows).to_parquet(OUTPUT, index=False)
+    print(f"Wrote {OUTPUT}: {len(rows)} rows")
+
+
+if __name__ == "__main__":
+    main()

features/extract_faces.py

@@ -0,0 +1,332 @@
+"""
+Face feature extractor — YuNet (YOLO-architecture, cv2.FaceDetectorYN).
+
+WHY YuNet over BlazeFace:
+  YuNet is specifically trained for face detection with a YOLO-style architecture.
+  It handles small, rotated, and stylised painted faces better than BlazeFace full-range
+  while producing fewer false positives at score_threshold=0.7.
+
+Each YuNet detection row: [x, y, w, h, re_x, re_y, le_x, le_y,
+                            nose_x, nose_y, rm_x, rm_y, lm_x, lm_y, score]
+  re = right eye, le = left eye, nose = nose tip, rm/lm = right/left mouth corner.
+
+Encodes each image as a 39-dim face vector:
+
+  Basic presence (3):
+  [0]  face_detected
+  [1]  log1p(n_faces) / log1p(10)   — normalised count
+  [2]  crowd indicator              — 1 if n_faces > 5
+
+  Coverage & size (5):
+  [3]  total_coverage               — Σ(bbox_area) / img_area
+  [4]  mean_face_size
+  [5]  max_face_size                — largest face / img_area
+  [6]  dominance_ratio              — max_size / mean_size
+  [7]  face_size_std
+
+  Size distribution (2):
+  [8]  size_entropy                 — entropy of normalised size distribution
+  [9]  largest_face_fraction        — max_size / total_coverage
+
+  Spatial centroid & spread (4):
+  [10] centroid_x                   — area-weighted
+  [11] centroid_y
+  [12] spread_x                     — σ of face x-centres
+  [13] spread_y
+
+  Orientation (4):
+  [14] mean_tilt                    — roll from eye vector / 90 (0 = level)
+  [15] tilt_std
+  [16] mean_frontal_score           — 1 = frontal, 0 = profile (nose-eye landmarks)
+  [17] frontal_ratio                — fraction of faces with frontal_score > 0.6
+
+  Composition (5):
+  [18] vertical_bias               — mean_cy - 0.5 (neg = upper, pos = lower)
+  [19] arrangement_rowness         — std_y / (std_x + ε): low = row, high = column
+  [20] mean_pairwise_dist          — mean normalised dist between all face pairs
+  [21] min_pairwise_dist           — closest pair distance
+  [22] clustering_score            — fraction of pairs within 0.15 distance
+
+  Spatial histograms (8):
+  [23-26] 4-bin horizontal histogram
+  [27-30] 4-bin vertical histogram
+
+  4×2 spatial grid (8):
+  [31-38] which grid cell(s) hold faces (4 horiz × 2 vert, row-major)
+
+Total: 39 dims.
+
+Output: Religion_art_dataset/features_faces.parquet
+  filename, face_detected, face_count, face_vector (list[float32], 39 dims)
+
+Usage:
+    python features/extract_faces.py
+    python features/extract_faces.py --limit 100
+"""
+
+import argparse
+import os
+import sys
+import urllib.request
+sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
+
+import cv2
+import numpy as np
+import pandas as pd
+from tqdm import tqdm
+
+IMAGES_DIR   = "data/images"
+METADATA_CSV = "data/artwork_metadata.csv"
+
+OUTPUT     = "data/features/faces.parquet"
+MODELS_DIR = os.path.join(os.path.dirname(__file__), "models")
+FACE_DIMS  = 39
+SCORE_THR  = 0.7
+NMS_THR    = 0.3
+
+MODEL_PATH = os.path.join(MODELS_DIR, "face_detection_yunet_2023mar.onnx")
+MODEL_URL  = (
+    "https://github.com/opencv/opencv_zoo/raw/main/models/"
+    "face_detection_yunet/face_detection_yunet_2023mar.onnx"
+)
+
+FACE_COLS = ["filename", "face_detected", "face_count", "face_vector"]
+
+
+def ensure_model():
+    os.makedirs(MODELS_DIR, exist_ok=True)
+    if not os.path.exists(MODEL_PATH):
+        print(f"Downloading YuNet model (~380 KB) → {MODEL_PATH}")
+        urllib.request.urlretrieve(MODEL_URL, MODEL_PATH)
+        print("Download complete.")
+
+
+def _zero_vec() -> list:
+    return [0.0] * FACE_DIMS
+
+
+def _size_entropy(sizes: np.ndarray) -> float:
+    if len(sizes) <= 1:
+        return 0.0
+    p = sizes / (sizes.sum() + 1e-10)
+    return float(-np.sum(p * np.log(p + 1e-10)))
+
+
+def _frontal_score(re_x, le_x, nose_x) -> float:
+    """
+    Estimate how frontal a face is from YuNet landmarks (all in normalised [0,1] coords).
+    Returns 1.0 for perfectly frontal, 0.0 for fully in profile.
+    """
+    eye_mid  = (re_x + le_x) / 2.0
+    eye_dist = abs(re_x - le_x)
+    nose_off = abs(nose_x - eye_mid)
+    profile  = nose_off / (eye_dist + 1e-6)
+    return float(max(0.0, 1.0 - min(profile, 1.0)))
+
+
+def _pairwise_stats(cx: np.ndarray, cy: np.ndarray) -> tuple:
+    n = len(cx)
+    if n < 2:
+        return 0.0, 0.0, 0.0
+    dists = []
+    for i in range(n):
+        for j in range(i + 1, n):
+            dists.append(float(np.sqrt((cx[i]-cx[j])**2 + (cy[i]-cy[j])**2)))
+    dists = np.array(dists)
+    return float(dists.mean()), float(dists.min()), float((dists < 0.15).mean())
+
+
+def encode_faces(faces, img_h: int, img_w: int) -> tuple:
+    """
+    Build a 39-dim face vector from YuNet detections.
+    faces: numpy array (N, 15) — None or empty → zero vector.
+    """
+    if faces is None or len(faces) == 0:
+        return 0, 0, _zero_vec()
+
+    vec      = np.zeros(FACE_DIMS, dtype=np.float32)
+    img_area = float(img_h * img_w) or 1.0
+    n        = len(faces)
+
+    # Normalise all coordinates to [0, 1]
+    sizes, cx_list, cy_list, tilts, frontal_scores = [], [], [], [], []
+
+    for f in faces:
+        x, y, w, h = f[0], f[1], f[2], f[3]
+        # normalised bbox
+        nw = w / img_w
+        nh = h / img_h
+        cx = (x + w / 2.0) / img_w
+        cy = (y + h / 2.0) / img_h
+        sizes.append(nw * nh)
+        cx_list.append(cx)
+        cy_list.append(cy)
+
+        # landmarks (pixel → normalised)
+        re_x, re_y = f[4] / img_w, f[5] / img_h
+        le_x, le_y = f[6] / img_w, f[7] / img_h
+        dx = re_x - le_x
+        dy = re_y - le_y
+        tilts.append(float(np.degrees(np.arctan2(dy, dx))))
+
+        nose_x = f[8] / img_w
+        frontal_scores.append(_frontal_score(re_x, le_x, nose_x))
+
+    sizes  = np.array(sizes,   dtype=np.float32)
+    cx_arr = np.array(cx_list, dtype=np.float32)
+    cy_arr = np.array(cy_list, dtype=np.float32)
+
+    # ── [0-2] basic presence ─────────────────────────────────────────────────
+    vec[0] = 1.0
+    vec[1] = float(np.log1p(n) / np.log1p(10))
+    vec[2] = float(n > 5)
+
+    # ── [3-7] coverage & size ────────────────────────────────────────────────
+    vec[3] = float(sizes.sum())
+    vec[4] = float(sizes.mean())
+    vec[5] = float(sizes.max())
+    vec[6] = float(sizes.max() / (sizes.mean() + 1e-6))
+    vec[7] = float(sizes.std()) if n > 1 else 0.0
+
+    # ── [8-9] size distribution ──────────────────────────────────────────────
+    vec[8] = _size_entropy(sizes)
+    vec[9] = float(sizes.max() / (sizes.sum() + 1e-6))
+
+    # ── [10-13] spatial centroid & spread ────────────────────────────────────
+    w_sum   = sizes.sum() + 1e-6
+    vec[10] = float((cx_arr * sizes).sum() / w_sum)
+    vec[11] = float((cy_arr * sizes).sum() / w_sum)
+    vec[12] = float(cx_arr.std()) if n > 1 else 0.0
+    vec[13] = float(cy_arr.std()) if n > 1 else 0.0
+
+    # ── [14-17] orientation ──────────────────────────────────────────────────
+    vec[14] = float(np.mean(tilts)) / 90.0
+    vec[15] = float(np.std(tilts))  / 90.0 if n > 1 else 0.0
+    fs_arr  = np.array(frontal_scores, dtype=np.float32)
+    vec[16] = float(fs_arr.mean())
+    vec[17] = float((fs_arr > 0.6).mean())
+
+    # ── [18-22] composition ──────────────────────────────────────────────────
+    vec[18] = float(cy_arr.mean()) - 0.5
+    vec[19] = float(cy_arr.std() / (cx_arr.std() + 1e-6)) if n > 1 else 0.0
+    mean_pd, min_pd, clust = _pairwise_stats(cx_arr, cy_arr)
+    vec[20] = mean_pd
+    vec[21] = min_pd
+    vec[22] = clust
+
+    # ── [23-26] horizontal histogram ─────────────────────────────────────────
+    h_hist, _ = np.histogram(cx_arr, bins=4, range=(0.0, 1.0))
+    vec[23:27] = h_hist.astype(np.float32) / (n + 1e-6)
+
+    # ── [27-30] vertical histogram ───────────────────────────────────────────
+    v_hist, _ = np.histogram(cy_arr, bins=4, range=(0.0, 1.0))
+    vec[27:31] = v_hist.astype(np.float32) / (n + 1e-6)
+
+    # ── [31-38] 4×2 spatial grid ─────────────────────────────────────────────
+    grid = np.zeros((2, 4), dtype=np.float32)
+    for cx, cy in zip(cx_list, cy_list):
+        r = min(int(cy * 2), 1)
+        c = min(int(cx * 4), 3)
+        grid[r, c] += 1.0
+    grid /= (n + 1e-6)
+    vec[31:39] = grid.ravel()
+
+    return 1, n, vec.tolist()
+
+
+def _is_correct(v) -> bool:
+    return hasattr(v, "__len__") and len(v) == FACE_DIMS
+
+
+def load_existing() -> pd.DataFrame:
+    if os.path.exists(OUTPUT):
+        df = pd.read_parquet(OUTPUT)
+        if "face_vector" not in df.columns:
+            return pd.DataFrame(columns=FACE_COLS)
+        return df[FACE_COLS]
+    return pd.DataFrame(columns=FACE_COLS)
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--limit",      type=int, default=None)
+    parser.add_argument("--save-every", type=int, default=500)
+    parser.add_argument("--score-thr",  type=float, default=SCORE_THR)
+    parser.add_argument("--nms-thr",    type=float, default=NMS_THR)
+    parser.add_argument("--subset",     default=None,
+                        help="CSV with a 'filename' column to restrict processing to")
+    args = parser.parse_args()
+
+    ensure_model()
+
+    meta = pd.read_csv(METADATA_CSV, dtype=str)[["filename"]]
+    if args.subset:
+        keep = set(pd.read_csv(args.subset, dtype=str)["filename"].tolist())
+        meta = meta[meta["filename"].isin(keep)].reset_index(drop=True)
+        print(f"Subset: {len(meta)} filenames from {args.subset}")
+    existing = load_existing()
+
+    if "face_vector" in existing.columns and len(existing):
+        correct_mask = existing["face_vector"].apply(_is_correct)
+        correct      = existing[correct_mask].copy()
+    else:
+        correct = pd.DataFrame(columns=FACE_COLS)
+
+    done_fns = set(correct["filename"].tolist())
+    todo     = meta[~meta["filename"].isin(done_fns)].reset_index(drop=True)
+    if args.limit:
+        todo = todo.head(args.limit)
+
+    n_stale = len(existing) - len(correct)
+    print(f"Faces (YuNet {FACE_DIMS}-dim, score_thr={args.score_thr}): "
+          f"{len(correct)} correct, {n_stale} stale, {len(todo)} new.")
+
+    if todo.empty:
+        print("Nothing to do.")
+        return
+
+    new_rows = []
+
+    for _, meta_row in tqdm(todo.iterrows(), total=len(todo), desc="Faces"):
+        fn       = meta_row["filename"]
+        img_path = os.path.join(IMAGES_DIR, fn)
+
+        detected, n_faces, face_vec = 0, 0, _zero_vec()
+
+        if os.path.exists(img_path):
+            img = cv2.imread(img_path)
+            if img is not None:
+                h, w = img.shape[:2]
+                detector = cv2.FaceDetectorYN.create(
+                    MODEL_PATH, "", (w, h),
+                    score_threshold=args.score_thr,
+                    nms_threshold=args.nms_thr,
+                )
+                _, faces = detector.detect(img)
+                detected, n_faces, face_vec = encode_faces(faces, h, w)
+
+        new_rows.append({
+            "filename":      fn,
+            "face_detected": detected,
+            "face_count":    n_faces,
+            "face_vector":   face_vec,
+        })
+
+        if len(new_rows) >= args.save_every:
+            correct = pd.concat([correct, pd.DataFrame(new_rows)], ignore_index=True)
+            correct.to_parquet(OUTPUT, index=False)
+            new_rows = []
+
+    if new_rows:
+        correct = pd.concat([correct, pd.DataFrame(new_rows)], ignore_index=True)
+
+    correct.to_parquet(OUTPUT, index=False)
+
+    n_det = int(correct["face_detected"].sum())
+    n_tot = len(correct)
+    print(f"Done. {n_tot} rows, {n_det} faces detected ({100*n_det/n_tot:.1f}%)")
+    print(f"Saved → {OUTPUT}")
+
+
+if __name__ == "__main__":
+    main()

features/extract_handcrafted.py

@@ -0,0 +1,240 @@
+"""
+Hand-crafted features for the gold 4x1000 subset — corrected pipeline.
+
+Mirrors notebooks/handcrafted.ipynb (2026-07-07):
+  1. crop_padding             — strip near-black letterbox borders
+  2. guarded rembg mask       — PRE-COMPUTED: data/masks/
+                                (verdicts.csv; mask applied only when it removes a
+                                solid, convex, edge-touching, uniform background)
+  3. applied images           — spatial views cropped to mask bbox; mask limits
+                                color/light stats. rejected images — full image.
+
+Differences vs extract_handcrafted.py: masking is guarded (not unconditional),
+spatial features get bbox-crop instead of nothing, no inline rembg (cache only).
+
+Output: data/features/handcrafted.parquet   (key: id, str)
+Usage:  python features/extract_handcrafted_gold.py [--workers 4]
+"""
+
+import argparse
+import os
+import sys
+from multiprocessing.pool import ThreadPool
+from pathlib import Path
+
+import cv2
+import numpy as np
+import pandas as pd
+from PIL import Image
+from skimage.feature import local_binary_pattern
+from skimage.segmentation import slic
+from tqdm import tqdm
+
+ROOT = Path(__file__).resolve().parent.parent
+IMAGES = ROOT / "data/images"
+MASK_DIR = ROOT / "data/masks"
+VERDICT_CSV = MASK_DIR / "verdicts.csv"
+SELECTED = ROOT / "data/artwork_metadata.csv"
+OUTPUT = ROOT / "data/features/handcrafted.parquet"
+
+HIST_BINS = (8, 4, 4)
+LBP_P = 8
+LBP_BINS = LBP_P * (LBP_P - 1) + 3
+MAX_SIDE = 1024  # cap resolution: texture/edge features stay comparable across
+                 # museum scan sizes; unbounded FFT/SLIC on 33 MP scans OOMs
+
+Image.MAX_IMAGE_PIXELS = None
+
+
+def crop_padding(img_rgb, threshold=5):
+    gray = cv2.cvtColor(img_rgb, cv2.COLOR_RGB2GRAY)
+    rows = np.where(gray.max(axis=1) > threshold)[0]
+    cols = np.where(gray.max(axis=0) > threshold)[0]
+    if len(rows) == 0 or len(cols) == 0:
+        return img_rgb
+    return img_rgb[rows[0]:rows[-1] + 1, cols[0]:cols[-1] + 1]
+
+
+def grey_world_normalize(img_rgb):
+    f = img_rgb.astype(np.float32)
+    means = f.reshape(-1, 3).mean(0) + 1e-6
+    f *= means.mean() / means
+    return np.clip(f, 0, 255).astype(np.uint8)
+
+
+VER = pd.read_csv(VERDICT_CSV, dtype=str).set_index("filename")
+
+
+def load_final(filename):
+    """(rgb, hsv, gray, edges, mask) under the corrected pipeline."""
+    img = crop_padding(np.array(Image.open(IMAGES / filename).convert("RGB")))
+    mask = None
+    if filename in VER.index:
+        v = VER.loc[filename]
+        if v["verdict"] == "applied":
+            m = cv2.imread(str(MASK_DIR / (Path(filename).stem + ".png")),
+                           cv2.IMREAD_GRAYSCALE)
+            if m is not None and m.shape == img.shape[:2]:
+                y0, y1 = int(v["y0"]), int(v["y1"])
+                x0, x1 = int(v["x0"]), int(v["x1"])
+                img, mask = img[y0:y1 + 1, x0:x1 + 1], m[y0:y1 + 1, x0:x1 + 1]
+    scale = MAX_SIDE / max(img.shape[:2])
+    if scale < 1.0:
+        size = (round(img.shape[1] * scale), round(img.shape[0] * scale))
+        img = cv2.resize(img, size, interpolation=cv2.INTER_AREA)
+        if mask is not None:
+            mask = cv2.resize(mask, size, interpolation=cv2.INTER_NEAREST)
+    hsv = cv2.cvtColor(img, cv2.COLOR_RGB2HSV)
+    gray = cv2.cvtColor(img, cv2.COLOR_RGB2GRAY)
+    return img, hsv, gray, cv2.Canny(gray, 100, 200), mask
+
+
+def extract_one(filename):
+    try:
+        img, hsv, gray, edges, mask = load_final(filename)
+        row = {"filename": filename, "hc_fg_applied": int(mask is not None)}
+
+        # color
+        hist = cv2.calcHist([hsv], [0, 1, 2], mask, list(HIST_BINS),
+                            [0, 180, 0, 256, 0, 256])
+        cv2.normalize(hist, hist)
+        for i, v in enumerate(hist.flatten()):
+            row[f"hc_hist_{i}"] = float(v)
+        hsv_n = cv2.cvtColor(grey_world_normalize(img), cv2.COLOR_RGB2HSV)
+        hist_n = cv2.calcHist([hsv_n], [0, 1, 2], mask, list(HIST_BINS),
+                              [0, 180, 0, 256, 0, 256])
+        cv2.normalize(hist_n, hist_n)
+        for i, v in enumerate(hist_n.flatten()):
+            row[f"hc_norm_hist_{i}"] = float(v)
+        h, s, v_ = cv2.split(hsv)
+        for pref, ch, bins, rng in [("h", h, 16, [0, 180]),
+                                    ("s", s, 8, [0, 256]),
+                                    ("v", v_, 8, [0, 256])]:
+            c = cv2.calcHist([ch], [0], mask, [bins], rng).flatten()
+            c /= c.sum() + 1e-10
+            for i, x in enumerate(c):
+                row[f"hc_{pref}_hist_{i}"] = float(x)
+
+        # light + color scalars (masked), edge density (full frame)
+        sel_g = gray if mask is None else gray[mask > 0]
+        sel_hsv = hsv.reshape(-1, 3) if mask is None else hsv[mask > 0]
+        row["hc_avg_hue"] = float(sel_hsv[:, 0].mean())
+        row["hc_avg_sat"] = float(sel_hsv[:, 1].mean())
+        row["hc_brightness"] = float(sel_hsv[:, 2].mean())
+        row["hc_contrast"] = float(sel_g.std())
+        row["hc_darkness"] = float((sel_g < 64).mean())
+        row["hc_edge_density"] = float((edges > 0).mean())
+
+        # symmetry
+        hh, ww = gray.shape
+        row["hc_sym_lr"] = 1.0 - float(np.abs(
+            gray[:, :ww // 2].astype(np.float32)
+            - np.fliplr(gray[:, ww - ww // 2:]).astype(np.float32)).mean()) / 255.0
+        row["hc_sym_tb"] = 1.0 - float(np.abs(
+            gray[:hh // 2, :].astype(np.float32)
+            - np.flipud(gray[hh - hh // 2:, :]).astype(np.float32)).mean()) / 255.0
+
+        # flatness
+        lab = cv2.cvtColor(img, cv2.COLOR_RGB2LAB).astype(np.float32)
+        segments = slic(lab / 255.0, n_segments=200, compactness=10,
+                        start_label=0, channel_axis=2)
+        stds = [[], [], []]
+        for sid in np.unique(segments):
+            region = lab[segments == sid]
+            if len(region) > 1:
+                for c in range(3):
+                    stds[c].append(float(region[:, c].std()))
+        sl, sa, sb = (float(np.mean(s_)) if s_ else 0.0 for s_ in stds)
+        row["hc_flatness_l"], row["hc_flatness_a"] = sl, sa
+        row["hc_flatness_b"], row["hc_flatness_mean"] = sb, (sl + sa + sb) / 3.0
+
+        # geometry
+        power = np.abs(np.fft.fftshift(np.fft.fft2(gray.astype(np.float32)))) ** 2
+        ph, pw = power.shape
+        cy, cx = ph // 2, pw // 2
+        r = np.sqrt((np.arange(pw) - cx) ** 2 + (np.arange(ph)[:, None] - cy) ** 2)
+        edges_r = np.logspace(0, np.log10(min(cx, cy)), 9)
+        bands = []
+        for lo, hi in zip(edges_r[:-1], edges_r[1:]):
+            sel = (r >= lo) & (r < hi)
+            bands.append(float(power[sel].mean()) if sel.any() else 0.0)
+        total = sum(bands) + 1e-10
+        for i, v in enumerate(bands):
+            row[f"hc_fft_band_{i}"] = v / total
+        lbp = local_binary_pattern(gray, P=LBP_P, R=1, method="nri_uniform")
+        lh, _ = np.histogram(lbp.ravel(), bins=LBP_BINS, range=(0, LBP_BINS))
+        lh = lh / (lh.sum() + 1e-10)
+        for i, v in enumerate(lh):
+            row[f"hc_lbp_{i}"] = float(v)
+
+        # lines
+        lines = cv2.HoughLinesP(edges, 1, np.pi / 180, threshold=50,
+                                minLineLength=20, maxLineGap=5)
+        if lines is not None:
+            total_len = float(sum(np.hypot(x2 - x1, y2 - y1)
+                                  for x1, y1, x2, y2 in lines[:, 0]))
+            hough_mask = np.zeros_like(edges)
+            for x1, y1, x2, y2 in lines[:, 0]:
+                cv2.line(hough_mask, (x1, y1), (x2, y2), 255, 1)
+            row["hc_hough_count"] = len(lines)
+            row["hc_hough_density"] = total_len / (hh * ww)
+            row["hc_straight_ratio"] = (float((hough_mask > 0).sum())
+                                        / (float((edges > 0).sum()) + 1e-10))
+        else:
+            row["hc_hough_count"] = 0
+            row["hc_hough_density"] = 0.0
+            row["hc_straight_ratio"] = 0.0
+        gx = cv2.Sobel(gray, cv2.CV_64F, 1, 0, ksize=3)
+        gy = cv2.Sobel(gray, cv2.CV_64F, 0, 1, ksize=3)
+        mag = np.hypot(gx, gy)
+        angle = np.degrees(np.arctan2(gy, gx)) % 180
+        ah, _ = np.histogram(angle.ravel(), bins=8, range=(0, 180),
+                             weights=mag.ravel())
+        ah = ah / (ah.sum() + 1e-10)
+        for i, v in enumerate(ah):
+            row[f"hc_angle_hist_{i}"] = float(v)
+
+        return row
+    except Exception as e:
+        sys.stderr.write(f"FAIL {filename}: {e}\n")
+        return None
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--workers", type=int, default=4)
+    ap.add_argument("--chunk", type=int, default=100)
+    args = ap.parse_args()
+
+    gold = (pd.read_csv(SELECTED, dtype=str)
+            .drop_duplicates("filename")[["filename"]])
+    existing = (pd.read_parquet(OUTPUT) if OUTPUT.exists()
+                else pd.DataFrame(columns=["filename"]))
+    have = set(existing["filename"])
+    todo = gold[~gold["filename"].isin(have)]
+    print(f"gold={len(gold)}  done={len(have)}  todo={len(todo)}")
+
+    tasks = todo["filename"].tolist()
+    new_rows, failed = [], 0
+    with ThreadPool(args.workers) as pool:
+        for row in tqdm(pool.imap_unordered(extract_one, tasks, chunksize=4),
+                        total=len(tasks)):
+            if row is None:
+                failed += 1
+                continue
+            new_rows.append(row)
+            if len(new_rows) >= args.chunk:
+                existing = pd.concat([existing, pd.DataFrame(new_rows)],
+                                     ignore_index=True)
+                existing.to_parquet(OUTPUT, index=False)
+                new_rows = []
+    if new_rows:
+        existing = pd.concat([existing, pd.DataFrame(new_rows)],
+                             ignore_index=True)
+    existing.to_parquet(OUTPUT, index=False)
+    print(f"Wrote {OUTPUT}: {len(existing)} rows, "
+          f"{len(existing.columns)} cols. Failures: {failed}")
+
+
+if __name__ == "__main__":
+    main()

features/extract_pose.py

@@ -0,0 +1,112 @@
+"""
+Main-figure pose extractor — gold 4x1000 subset.
+
+Tests upgrade (a) from the pose investigation: instead of averaging all
+skeletons in an image (extract_pose.py), store ONLY the largest detected
+figure's torso-normalised skeleton, plus quality indicators so garbage
+detections can be filtered in analysis:
+
+  filename
+  n_persons        — YOLO detections in the image
+  main_conf        — box confidence of the largest figure
+  main_kpt_conf    — mean keypoint confidence of the largest figure
+  main_torso_px    — torso height in pixels (tiny => unreliable normalisation)
+  main_area        — bbox area fraction of the image
+  main_skel_0..33  — 17 kpts x (dx,dy), torso-normalised, 0 where invisible
+
+Output: data/features/pose.parquet   (checkpointed, resumable)
+Usage:  python features/extract_pose_main_gold.py [--model yolov8m-pose.pt]
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+from tqdm import tqdm
+
+ROOT = Path(__file__).resolve().parent.parent
+IMAGES = ROOT / "data/images"
+SELECTED = ROOT / "data/artwork_metadata.csv"
+OUTPUT = ROOT / "data/features/pose.parquet"
+
+KPT_THR = 0.3
+L_SHOULDER, R_SHOULDER, L_HIP, R_HIP = 5, 6, 11, 12
+
+
+def normalise_skeleton(kpts, conf):
+    """Torso-normalised skeleton (matches extract_pose.py) + torso height px."""
+    vis = conf >= KPT_THR
+    anchors = [L_SHOULDER, R_SHOULDER, L_HIP, R_HIP]
+    if sum(vis[i] for i in anchors) >= 2:
+        mid_shoulder = (kpts[L_SHOULDER] + kpts[R_SHOULDER]) / 2.0
+        mid_hip = (kpts[L_HIP] + kpts[R_HIP]) / 2.0
+        centre = (mid_shoulder + mid_hip) / 2.0
+        height = float(np.linalg.norm(mid_shoulder - mid_hip))
+    else:
+        visible = kpts[vis]
+        if len(visible) == 0:
+            return np.zeros(34, dtype=np.float32), 0.0
+        centre = visible.mean(axis=0)
+        height = float(np.linalg.norm(visible.max(axis=0) - visible.min(axis=0)))
+    norm = (kpts - centre) / max(height, 1.0)
+    norm[~vis] = 0.0
+    return norm.ravel().astype(np.float32), height
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--model", default="yolov8m-pose.pt")
+    ap.add_argument("--save-every", type=int, default=200)
+    args = ap.parse_args()
+
+    from ultralytics import YOLO
+    model = YOLO(args.model)
+
+    gold = (pd.read_csv(SELECTED, dtype=str)
+            .drop_duplicates("filename")[["filename"]])
+    existing = (pd.read_parquet(OUTPUT) if OUTPUT.exists()
+                else pd.DataFrame(columns=["filename"]))
+    have = set(existing["filename"])
+    todo = gold[~gold["filename"].isin(have)]["filename"].tolist()
+    print(f"gold={len(gold)}  done={len(have)}  todo={len(todo)}")
+
+    rows, failed = [], 0
+    for filename in tqdm(todo):
+        try:
+            res = model(str(IMAGES / filename), verbose=False)[0]
+            row = {"filename": filename, "n_persons": 0, "main_conf": 0.0,
+                   "main_kpt_conf": 0.0, "main_torso_px": 0.0, "main_area": 0.0,
+                   **{f"main_skel_{i}": 0.0 for i in range(34)}}
+            if res.boxes is not None and len(res.boxes) > 0:
+                areas = ((res.boxes.xyxy[:, 2] - res.boxes.xyxy[:, 0])
+                         * (res.boxes.xyxy[:, 3] - res.boxes.xyxy[:, 1]))
+                j = int(areas.argmax())
+                kpts = res.keypoints.xy[j].cpu().numpy()
+                conf = (res.keypoints.conf[j].cpu().numpy()
+                        if res.keypoints.conf is not None else np.ones(17))
+                skel, torso = normalise_skeleton(kpts, conf)
+                ih, iw = res.orig_shape
+                row.update({"n_persons": len(res.boxes),
+                            "main_conf": float(res.boxes.conf[j]),
+                            "main_kpt_conf": float(conf.mean()),
+                            "main_torso_px": torso,
+                            "main_area": float(areas[j]) / (ih * iw)})
+                row.update({f"main_skel_{i}": float(v) for i, v in enumerate(skel)})
+            rows.append(row)
+        except Exception as e:
+            failed += 1
+            sys.stderr.write(f"FAIL {filename}: {e}\n")
+        if len(rows) >= args.save_every:
+            existing = pd.concat([existing, pd.DataFrame(rows)], ignore_index=True)
+            existing.to_parquet(OUTPUT, index=False)
+            rows = []
+    if rows:
+        existing = pd.concat([existing, pd.DataFrame(rows)], ignore_index=True)
+    existing.to_parquet(OUTPUT, index=False)
+    print(f"Wrote {OUTPUT}: {len(existing)} rows. Failures: {failed}")
+
+
+if __name__ == "__main__":
+    main()

preprocessing/README.md

@@ -0,0 +1,20 @@
+# Preprocessing
+
+`generate_masks.py` produces the guarded background masks used by the
+hand-crafted feature extractor.
+
+Museum photographs often include a backdrop, mount or frame around the
+artwork. Removing it helps color/light statistics — but salient-object
+segmentation (U^2-Net) applied blindly also eats painted borders, halos and
+dark backgrounds that ARE the artwork. So every mask must pass five checks
+before it is applied (see the module docstring); otherwise the full image is
+used. On the gold set this accepts ~10% of images.
+
+Downstream use (in `features/extract_handcrafted.py`):
+
+- **applied** images: spatial features see the mask's bounding-box crop;
+  color/light statistics additionally exclude background pixels inside it.
+  Background is never zero-filled — that would create fake edges.
+- **rejected** images: full image everywhere.
+
+Outputs: `data/masks/<stem>.png` + `data/masks/verdicts.csv`.

preprocessing/generate_masks.py

@@ -0,0 +1,118 @@
+"""
+Guarded background masking with U^2-Net (rembg).
+
+For every image: strip near-black padding, run salient-object segmentation,
+then ACCEPT the mask only if it clearly removes a plain photographic backdrop
+around the artwork — never content. Five checks, all must pass:
+
+  1. kept fraction in [0.20, 0.90]      — mask keeps a plausible artwork share
+  2. no interior holes (> 2%)           — artwork regions are never punched out
+  3. convex solidity >= 0.97            — one solid blob, not scattered figures
+  4. mask must not touch-fill the border — something around it was removed
+  5. removed pixels are uniform (std <= 28) — what's removed looks like backdrop
+
+Accepted masks ("applied") are saved as PNGs + a bbox; everything else is
+"rejected" and downstream features use the full image. On our gold set this
+applies to ~10% of images (museum photos of framed/mounted works).
+
+Output: data/masks/<stem>.png + data/masks/verdicts.csv
+        (filename, verdict, y0, y1, x0, x1)
+Usage:  python preprocessing/generate_masks.py
+"""
+
+import csv
+from pathlib import Path
+
+import cv2
+import numpy as np
+import pandas as pd
+from PIL import Image
+from rembg import new_session, remove
+from tqdm import tqdm
+
+IMAGES = Path("data/images")
+SELECTED = Path("data/artwork_metadata.csv")
+MASK_DIR = Path("data/masks")
+VERDICTS = MASK_DIR / "verdicts.csv"
+
+Image.MAX_IMAGE_PIXELS = None
+
+
+def crop_padding(img_rgb, threshold=5):
+    gray = cv2.cvtColor(img_rgb, cv2.COLOR_RGB2GRAY)
+    rows = np.where(gray.max(axis=1) > threshold)[0]
+    cols = np.where(gray.max(axis=0) > threshold)[0]
+    if len(rows) == 0 or len(cols) == 0:
+        return img_rgb
+    return img_rgb[rows[0]:rows[-1] + 1, cols[0]:cols[-1] + 1]
+
+
+def mask_verdict(raw, img, lo=0.20, hi=0.90, max_bg_std=28):
+    """True (apply) only if the mask removes a solid, uniform border region."""
+    if raw is None:
+        return False
+    m = (raw > 0).astype(np.uint8)
+    kept = m.mean()
+    if not (lo <= kept <= hi):
+        return False
+    cnts, _ = cv2.findContours(m, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+    if not cnts:
+        return False
+    filled = m.copy()
+    cv2.drawContours(filled, cnts, -1, 1, -1)
+    if (filled - m).sum() / max(m.sum(), 1) > 0.02:
+        return False
+    hull = cv2.convexHull(np.vstack([c.reshape(-1, 2) for c in cnts]))
+    if cv2.contourArea(hull) == 0 or m.sum() / cv2.contourArea(hull) < 0.97:
+        return False
+    border = np.zeros_like(m)
+    border[0, :] = border[-1, :] = border[:, 0] = border[:, -1] = 1
+    if (border & (1 - m)).sum() == 0:
+        return False
+    removed = img[m == 0]
+    if removed.std(axis=0).mean() > max_bg_std:
+        return False
+    return True
+
+
+def main():
+    MASK_DIR.mkdir(parents=True, exist_ok=True)
+    sel = pd.read_csv(SELECTED, dtype=str).drop_duplicates("filename")
+    done = set()
+    if VERDICTS.exists():
+        done = set(pd.read_csv(VERDICTS, dtype=str)["filename"])
+    todo = [f for f in sel["filename"] if f not in done]
+    print(f"total={len(sel)}  done={len(done)}  todo={len(todo)}")
+
+    session = new_session("u2net")
+    mode = "a" if VERDICTS.exists() else "w"
+    with open(VERDICTS, mode, newline="") as fh:
+        writer = csv.writer(fh)
+        if mode == "w":
+            writer.writerow(["filename", "verdict", "y0", "y1", "x0", "x1"])
+        applied = rejected = 0
+        for fn in tqdm(todo):
+            try:
+                img = crop_padding(np.array(Image.open(IMAGES / fn).convert("RGB")))
+                raw = np.array(remove(Image.fromarray(img), session=session,
+                                      only_mask=True))
+                if mask_verdict(raw, img):
+                    m = (raw > 0).astype(np.uint8)
+                    ys, xs = np.where(m > 0)
+                    y0, y1, x0, x1 = ys.min(), ys.max(), xs.min(), xs.max()
+                    cv2.imwrite(str(MASK_DIR / (Path(fn).stem + ".png")), m * 255)
+                    writer.writerow([fn, "applied", y0, y1, x0, x1])
+                    applied += 1
+                else:
+                    writer.writerow([fn, "rejected", "", "", "", ""])
+                    rejected += 1
+            except Exception as e:
+                print(f"FAIL {fn}: {e}")
+                writer.writerow([fn, "rejected", "", "", "", ""])
+                rejected += 1
+            fh.flush()
+    print(f"applied={applied}  rejected={rejected}")
+
+
+if __name__ == "__main__":
+    main()

requirements.txt

@@ -0,0 +1,24 @@
+# core
+numpy
+pandas
+pyarrow
+tqdm
+pillow
+opencv-python-headless
+scikit-image
+scikit-learn
+scipy
+
+# preprocessing
+rembg
+
+# deep features
+torch
+torchvision
+git+https://github.com/openai/CLIP.git
+ultralytics
+
+# app
+fastapi
+uvicorn[standard]
+openTSNE