Add Gradio app, requirements and timeline encodings

README.md

@@ -1,6 +1,6 @@
 ---
 title: Timeline Vlm
-emoji: 🐨
+emoji: 🕰️
 colorFrom: purple
 colorTo: blue
 sdk: gradio
@@ -9,4 +9,11 @@ app_file: app.py
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🕰️ Timeline VLM — Visual Artifact Year Estimation
+
+Demo for the paper **[Can Vision-Language Models Tell When Things Were Made?](https://arxiv.org/pdf/2510.19559)**
+
+Upload images of visual artifacts (paintings, photographs, architecture, sculptures…) and the
+model estimates **when they were created** by projecting CLIP embeddings onto a learned temporal Bézier curve.
+
+📄 [Paper](https://arxiv.org/pdf/2510.19559) · 💻 [GitHub](https://github.com/TekayaNidham/timeline-vlm)

app.py

@@ -0,0 +1,295 @@
+from flask import Flask, request, jsonify, render_template, send_from_directory
+import numpy as np
+import os
+import torch
+import clip
+from PIL import Image
+from sklearn.decomposition import KernelPCA
+import io
+import base64
+import traceback
+import matplotlib
+matplotlib.use('Agg')
+import matplotlib.pyplot as plt
+from matplotlib.colors import Normalize
+import matplotlib.cm as cm
+from matplotlib.lines import Line2D
+import uuid
+import shutil
+import atexit
+
+app = Flask(__name__, static_folder='static', template_folder='templates')
+
+DATA_PATHS = {
+    'clip': {
+        'timeline_embeddings': 'encodings/timeline_embeddings.npy',
+        'timeline_labels':     'encodings/timeline_labels.txt',
+    },
+    'eva': {
+        'timeline_embeddings': 'encodings/eva/eva_timeline_embeddings.npy',
+        'timeline_labels':     'encodings/eva/eva_labels_timeline.txt',
+    },
+}
+
+UPLOAD_FOLDER = 'static/uploads'
+os.makedirs(UPLOAD_FOLDER, exist_ok=True)
+
+# Per-session state (in-memory; fine for a demo)
+_session_embeddings: dict[str, list] = {}
+_session_labels:     dict[str, list] = {}
+_session_paths:      dict[str, list] = {}
+
+# ── CLIP model ────────────────────────────────────────────────────────────────
+try:
+    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+    model, preprocess = clip.load("ViT-B/32", device=device)
+    CLIP_AVAILABLE = True
+    print(f"CLIP loaded on {device}")
+except Exception as e:
+    CLIP_AVAILABLE = False
+    print(f"CLIP not available: {e}")
+
+
+# ── Core math ─────────────────────────────────────────────────────────────────
+def de_casteljau(pts, t):
+    pts = pts.copy()
+    for r in range(1, len(pts)):
+        pts[: len(pts) - r] = (1 - t) * pts[: len(pts) - r] + t * pts[1 : len(pts) - r + 1]
+    return pts[0]
+
+
+def bezier_curve(control_points, num_points=1000):
+    return np.array([de_casteljau(control_points, t) for t in np.linspace(0, 1, num_points)])
+
+
+def project_onto_curve(points, curve):
+    projected, indices = [], []
+    for p in points:
+        d = np.linalg.norm(curve - p, axis=1)
+        idx = np.argmin(d)
+        projected.append(curve[idx])
+        indices.append(idx)
+    return np.array(projected), np.array(indices)
+
+
+# ── Encoding ──────────────────────────────────────────────────────────────────
+def encode_image(image_bytes: bytes) -> np.ndarray:
+    if not CLIP_AVAILABLE:
+        return np.random.randn(512)
+    img = Image.open(io.BytesIO(image_bytes)).convert("RGB")
+    tensor = preprocess(img).unsqueeze(0).to(device)
+    with torch.no_grad():
+        emb = model.encode_image(tensor).cpu().numpy().flatten()
+    return emb
+
+
+# ── Embedding pipeline ────────────────────────────────────────────────────────
+def load_embeddings(data_type: str = 'clip'):
+    paths = DATA_PATHS[data_type]
+    try:
+        embeddings = np.load(paths['timeline_embeddings'])
+        with open(paths['timeline_labels']) as f:
+            labels = [l.strip() for l in f]
+        return embeddings, labels
+    except FileNotFoundError:
+        print("Embedding files not found – using synthetic data.")
+        embeddings = np.random.randn(20, 512)
+        labels = [str(1700 + i * 15) for i in range(20)]
+        return embeddings, labels
+
+
+def process_embeddings(timeline_embs, timeline_labels, dimension=3,
+                       n_ctrl=300, user_embs=None, user_labels=None, user_paths=None):
+    kpca = KernelPCA(n_components=dimension, kernel="cosine")
+    reduced = kpca.fit_transform(timeline_embs)
+
+    idx = np.linspace(0, len(reduced) - 1, min(n_ctrl, len(reduced)), dtype=int)
+    ctrl = reduced[idx]
+    curve = bezier_curve(ctrl, num_points=1000)
+    proj_text, text_idx = project_onto_curve(reduced, curve)
+
+    years = []
+    for lbl in timeline_labels:
+        try:
+            years.append(int(lbl))
+        except ValueError:
+            years.append(1900)
+
+    out = dict(reduced_text=reduced, projected_text=proj_text,
+               text_indices=text_idx, bezier_points=curve,
+               years=years, timeline_labels=timeline_labels)
+
+    if user_embs and len(user_embs) > 0:
+        r_user = kpca.transform(np.array(user_embs))
+        p_user, u_idx = project_onto_curve(r_user, curve)
+        out.update(reduced_uploads=r_user, projected_uploads=p_user,
+                   upload_indices=u_idx, upload_labels=user_labels,
+                   upload_paths=user_paths)
+    return out
+
+
+# ── Matplotlib 3-D visualisation ──────────��───────────────────────────────────
+def make_figure(data, show_original=False) -> str:
+    reduced    = data['reduced_text']
+    projected  = data['projected_text']
+    curve      = data['bezier_points']
+    years      = data['years']
+
+    fig = plt.figure(figsize=(13, 10))
+    ax  = fig.add_subplot(111, projection='3d')
+
+    norm = Normalize(vmin=min(years), vmax=max(years))
+    cmap = cm.viridis
+
+    if show_original:
+        ax.scatter(*reduced.T, c=years, cmap='viridis', s=20, alpha=0.4,
+                   label='Original embeddings')
+
+    sc = ax.scatter(*projected.T, c=years, cmap='viridis', s=35,
+                    label='Projected points', zorder=5)
+    ax.plot(*curve.T, 'r-', linewidth=1.2, label='Bézier curve', zorder=10)
+
+    # Year annotations every ~10 ticks
+    step = max(1, (max(years) - min(years)) // 11)
+    annotated = set(range(min(years), max(years) + 1, step))
+    for yr, pt in zip(years, projected):
+        if yr in annotated:
+            ax.text(pt[0], pt[1], pt[2], str(yr), fontsize=7,
+                    ha='right', color='#222')
+
+    # User images
+    if 'projected_uploads' in data:
+        pu      = data['projected_uploads']
+        u_idx   = data['upload_indices']
+        t_idx   = data['text_indices']
+        t_lbls  = data['timeline_labels']
+
+        for i, pt in enumerate(pu):
+            lifted     = pt.copy(); lifted[2] += 0.02
+            ax.scatter(*lifted, c='gold', marker='*', s=600,
+                       edgecolors='black', linewidth=1.5, zorder=1000)
+            near = np.argmin(np.abs(t_idx - u_idx[i]))
+            pred_yr = t_lbls[near]
+            ax.text(lifted[0], lifted[1], lifted[2] + 0.01,
+                    f"~{pred_yr}", fontsize=8, color='darkred', fontweight='bold')
+
+        ax.legend(handles=[
+            Line2D([0],[0], marker='*', color='w', markerfacecolor='gold',
+                   markersize=14, label='Your images', markeredgecolor='black')
+        ], loc='upper right', fontsize=9)
+
+    cbar = plt.colorbar(sc, ax=ax, pad=0.05, shrink=0.55)
+    cbar.set_label('Year')
+    ax.set_xlabel('Dim 1'); ax.set_ylabel('Dim 2'); ax.set_zlabel('Dim 3')
+    ax.view_init(elev=30, azim=45)
+    plt.tight_layout()
+
+    buf = io.BytesIO()
+    plt.savefig(buf, format='png', dpi=130, bbox_inches='tight')
+    plt.close(fig)
+    buf.seek(0)
+    return base64.b64encode(buf.read()).decode()
+
+
+# ── Routes ────────────────────────────────────────────────────────────────────
+@app.route('/')
+def index():
+    return render_template('index.html')
+
+
+@app.route('/static/<path:path>')
+def serve_static(path):
+    return send_from_directory('static', path)
+
+
+@app.route('/api/visualize')
+def api_visualize():
+    data_type    = request.args.get('type', 'clip')
+    n_ctrl       = int(request.args.get('controlPoints', 300))
+    show_orig    = request.args.get('showOriginal', 'false').lower() == 'true'
+    session_id   = request.args.get('sessionId', 'default')
+
+    try:
+        t_embs, t_lbls = load_embeddings(data_type)
+
+        u_embs  = _session_embeddings.get(session_id, [])
+        u_lbls  = _session_labels.get(session_id, [])
+        u_paths = _session_paths.get(session_id, [])
+
+        vis_data = process_embeddings(t_embs, t_lbls, dimension=3,
+                                      n_ctrl=n_ctrl,
+                                      user_embs=u_embs or None,
+                                      user_labels=u_lbls or None,
+                                      user_paths=u_paths or None)
+        img_b64 = make_figure(vis_data, show_original=show_orig)
+
+        # Build prediction list
+        predictions = []
+        if 'upload_indices' in vis_data:
+            t_idx   = vis_data['text_indices']
+            u_idx   = vis_data['upload_indices']
+            t_lbls_ = vis_data['timeline_labels']
+            for i, lbl in enumerate(vis_data['upload_labels']):
+                near     = np.argmin(np.abs(t_idx - u_idx[i]))
+                pred_yr  = t_lbls_[near]
+                conf     = max(0, 100 - abs(int(u_idx[i]) - int(t_idx[near])) / 10)
+                predictions.append({
+                    'label':      lbl,
+                    'year':       pred_yr,
+                    'confidence': f"{conf:.1f}%",
+                    'path':       vis_data['upload_paths'][i],
+                })
+
+        return jsonify(success=True, visualization=img_b64, predictions=predictions)
+
+    except Exception as e:
+        traceback.print_exc()
+        return jsonify(success=False, error=str(e))
+
+
+@app.route('/api/encode', methods=['POST'])
+def api_encode():
+    if 'image' not in request.files:
+        return jsonify(success=False, error="No image in request")
+    file       = request.files['image']
+    session_id = request.form.get('sessionId', 'default')
+
+    fname    = f"{uuid.uuid4()}_{file.filename}"
+    fpath    = os.path.join(UPLOAD_FOLDER, fname)
+    file.save(fpath)
+
+    with open(fpath, 'rb') as f:
+        emb = encode_image(f.read())
+
+    _session_embeddings.setdefault(session_id, []).append(emb)
+    _session_labels.setdefault(session_id, []).append(file.filename)
+    _session_paths.setdefault(session_id, []).append(f"/static/uploads/{fname}")
+
+    return jsonify(success=True, filename=file.filename,
+                   path=f"/static/uploads/{fname}")
+
+
+@app.route('/api/reset', methods=['POST'])
+def api_reset():
+    session_id = request.form.get('sessionId', 'default')
+    for store in (_session_embeddings, _session_labels, _session_paths):
+        store.pop(session_id, None)
+    # Clean upload folder
+    for fn in os.listdir(UPLOAD_FOLDER):
+        fp = os.path.join(UPLOAD_FOLDER, fn)
+        try:
+            if os.path.isfile(fp):
+                os.unlink(fp)
+        except Exception:
+            pass
+    return jsonify(success=True)
+
+
+@atexit.register
+def _cleanup():
+    if os.path.exists(UPLOAD_FOLDER):
+        shutil.rmtree(UPLOAD_FOLDER, ignore_errors=True)
+
+
+if __name__ == '__main__':
+    app.run(host='0.0.0.0', port=7860, debug=False)

encodings/eva/eva_labels_timeline.txt

@@ -0,0 +1,324 @@
+1700
+1701
+1702
+1703
+1704
+1705
+1706
+1707
+1708
+1709
+1710
+1711
+1712
+1713
+1714
+1715
+1716
+1717
+1718
+1719
+1720
+1721
+1722
+1723
+1724
+1725
+1726
+1727
+1728
+1729
+1730
+1731
+1732
+1733
+1734
+1735
+1736
+1737
+1738
+1739
+1740
+1741
+1742
+1743
+1744
+1745
+1746
+1747
+1748
+1749
+1750
+1751
+1752
+1753
+1754
+1755
+1756
+1757
+1758
+1759
+1760
+1761
+1762
+1763
+1764
+1765
+1766
+1767
+1768
+1769
+1770
+1771
+1772
+1773
+1774
+1775
+1776
+1777
+1778
+1779
+1780
+1781
+1782
+1783
+1784
+1785
+1786
+1787
+1788
+1789
+1790
+1791
+1792
+1793
+1794
+1795
+1796
+1797
+1798
+1799
+1800
+1801
+1802
+1803
+1804
+1805
+1806
+1807
+1808
+1809
+1810
+1811
+1812
+1813
+1814
+1815
+1816
+1817
+1818
+1819
+1820
+1821
+1822
+1823
+1824
+1825
+1826
+1827
+1828
+1829
+1830
+1831
+1832
+1833
+1834
+1835
+1836
+1837
+1838
+1839
+1840
+1841
+1842
+1843
+1844
+1845
+1846
+1847
+1848
+1849
+1850
+1851
+1852
+1853
+1854
+1855
+1856
+1857
+1858
+1859
+1860
+1861
+1862
+1863
+1864
+1865
+1866
+1867
+1868
+1869
+1870
+1871
+1872
+1873
+1874
+1875
+1876
+1877
+1878
+1879
+1880
+1881
+1882
+1883
+1884
+1885
+1886
+1887
+1888
+1889
+1890
+1891
+1892
+1893
+1894
+1895
+1896
+1897
+1898
+1899
+1900
+1901
+1902
+1903
+1904
+1905
+1906
+1907
+1908
+1909
+1910
+1911
+1912
+1913
+1914
+1915
+1916
+1917
+1918
+1919
+1920
+1921
+1922
+1923
+1924
+1925
+1926
+1927
+1928
+1929
+1930
+1931
+1932
+1933
+1934
+1935
+1936
+1937
+1938
+1939
+1940
+1941
+1942
+1943
+1944
+1945
+1946
+1947
+1948
+1949
+1950
+1951
+1952
+1953
+1954
+1955
+1956
+1957
+1958
+1959
+1960
+1961
+1962
+1963
+1964
+1965
+1966
+1967
+1968
+1969
+1970
+1971
+1972
+1973
+1974
+1975
+1976
+1977
+1978
+1979
+1980
+1981
+1982
+1983
+1984
+1985
+1986
+1987
+1988
+1989
+1990
+1991
+1992
+1993
+1994
+1995
+1996
+1997
+1998
+1999
+2000
+2001
+2002
+2003
+2004
+2005
+2006
+2007
+2008
+2009
+2010
+2011
+2012
+2013
+2014
+2015
+2016
+2017
+2018
+2019
+2020
+2021
+2022
+2023

encodings/eva/eva_timeline_embeddings.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:df73efb267fd7e9f81d4181cad642c82aab05afb3f3ae55dafc23d2291b961b0
+size 331904

encodings/timeline_embeddings.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6cca6694dcb61653c3c0e586d0f2b1210548f6d639bc44240b53fee0ea863206
+size 665728

encodings/timeline_labels.txt

@@ -0,0 +1,325 @@
+1700
+1701
+1702
+1703
+1704
+1705
+1706
+1707
+1708
+1709
+1710
+1711
+1712
+1713
+1714
+1715
+1716
+1717
+1718
+1719
+1720
+1721
+1722
+1723
+1724
+1725
+1726
+1727
+1728
+1729
+1730
+1731
+1732
+1733
+1734
+1735
+1736
+1737
+1738
+1739
+1740
+1741
+1742
+1743
+1744
+1745
+1746
+1747
+1748
+1749
+1750
+1751
+1752
+1753
+1754
+1755
+1756
+1757
+1758
+1759
+1760
+1761
+1762
+1763
+1764
+1765
+1766
+1767
+1768
+1769
+1770
+1771
+1772
+1773
+1774
+1775
+1776
+1777
+1778
+1779
+1780
+1781
+1782
+1783
+1784
+1785
+1786
+1787
+1788
+1789
+1790
+1791
+1792
+1793
+1794
+1795
+1796
+1797
+1798
+1799
+1800
+1801
+1802
+1803
+1804
+1805
+1806
+1807
+1808
+1809
+1810
+1811
+1812
+1813
+1814
+1815
+1816
+1817
+1818
+1819
+1820
+1821
+1822
+1823
+1824
+1825
+1826
+1827
+1828
+1829
+1830
+1831
+1832
+1833
+1834
+1835
+1836
+1837
+1838
+1839
+1840
+1841
+1842
+1843
+1844
+1845
+1846
+1847
+1848
+1849
+1850
+1851
+1852
+1853
+1854
+1855
+1856
+1857
+1858
+1859
+1860
+1861
+1862
+1863
+1864
+1865
+1866
+1867
+1868
+1869
+1870
+1871
+1872
+1873
+1874
+1875
+1876
+1877
+1878
+1879
+1880
+1881
+1882
+1883
+1884
+1885
+1886
+1887
+1888
+1889
+1890
+1891
+1892
+1893
+1894
+1895
+1896
+1897
+1898
+1899
+1900
+1901
+1902
+1903
+1904
+1905
+1906
+1907
+1908
+1909
+1910
+1911
+1912
+1913
+1914
+1915
+1916
+1917
+1918
+1919
+1920
+1921
+1922
+1923
+1924
+1925
+1926
+1927
+1928
+1929
+1930
+1931
+1932
+1933
+1934
+1935
+1936
+1937
+1938
+1939
+1940
+1941
+1942
+1943
+1944
+1945
+1946
+1947
+1948
+1949
+1950
+1951
+1952
+1953
+1954
+1955
+1956
+1957
+1958
+1959
+1960
+1961
+1962
+1963
+1964
+1965
+1966
+1967
+1968
+1969
+1970
+1971
+1972
+1973
+1974
+1975
+1976
+1977
+1978
+1979
+1980
+1981
+1982
+1983
+1984
+1985
+1986
+1987
+1988
+1989
+1990
+1991
+1992
+1993
+1994
+1995
+1996
+1997
+1998
+1999
+2000
+2001
+2002
+2003
+2004
+2005
+2006
+2007
+2008
+2009
+2010
+2011
+2012
+2013
+2014
+2015
+2016
+2017
+2018
+2019
+2020
+2021
+2022
+2023
+2024

requirements.txt

@@ -0,0 +1,7 @@
+torch
+torchvision
+git+https://github.com/openai/CLIP.git
+Pillow
+scikit-learn
+matplotlib
+numpy