stuff

app.py

@@ -1,161 +1,4 @@
 # app.py
-# Full Streamlit app:
-# - Uses Hugging Face "transformers" (AutoTokenizer/AutoModel) with mean pooling
-# - Generates 3 random mixed datasets at startup (21 items each; 7 from 3 random base sets)
-# - Mixed set names are lowercase and look like "sports/countries/fruits"
-# - Model selector + 2D/3D toggle + Info button on the same row (compact)
-# - Local info page via st.query_params["page"] ("demo" or "info")
-# - 3D view has opaque pastelimport streamlit as st
-import plotly.graph_objects as go
-import numpy as np
-import random
-from transformers import AutoTokenizer, AutoModel
-import torch
-from sklearn.decomposition import PCA
-
-# ----------------------------
-# CONFIG
-# ----------------------------
-st.set_page_config(page_title="Embedding Demo", layout="wide")
-
-# embedding models
-EMBED_MODELS = {
-    "all-minilm-l6-v2": "sentence-transformers/all-MiniLM-L6-v2",
-    "all-mpnet-base-v2": "sentence-transformers/all-mpnet-base-v2",
-    "multi-qa-mpnet-base-dot-v1": "sentence-transformers/multi-qa-mpnet-base-dot-v1"
-}
-
-# base datasets
-DATASETS = {
-    "countries": ["germany", "france", "italy", "spain", "portugal", "poland", "netherlands", "belgium", "austria", "switzerland"],
-    "animals": ["cat", "dog", "lion", "tiger", "bear", "wolf", "fox", "eagle", "shark", "whale"],
-    "furniture": ["armchair","sofa","dining table","coffee table","bookshelf","bed","wardrobe","desk","office chair","dresser","nightstand","side table","tv stand","loveseat","chaise lounge","bench","hutch","kitchen island","futon","recliner","ottoman","console table","vanity","buffet","sectional sofa"],
-    "actors": ["brad pitt","angelina jolie","meryl streep","leonardo dicaprio","tom hanks","scarlett johansson","robert de niro","natalie portman","matt damon","cate blanchett"],
-    "rock group": ["beatles","rolling stones","pink floyd","queen","led zeppelin","u2","ac/dc","nirvana","radiohead","metallica"]
-}
-
-# ----------------------------
-# RANDOM MIXED SETS
-# ----------------------------
-def make_mixed_sets():
-    keys = list(DATASETS.keys())
-    mixed_sets = {}
-    for i in range(3):
-        src = random.sample(keys, 3)
-        words = []
-        for s in src:
-            words += random.sample(DATASETS[s], min(7, len(DATASETS[s])))
-        name = "/".join(src)
-        mixed_sets[name] = words
-    return mixed_sets
-
-DATASETS.update(make_mixed_sets())
-
-# ----------------------------
-# EMBEDDING CACHING
-# ----------------------------
-@st.cache_resource
-def load_model(model_name):
-    tokenizer = AutoTokenizer.from_pretrained(model_name)
-    model = AutoModel.from_pretrained(model_name)
-    return tokenizer, model
-
-def embed_words(tokenizer, model, words):
-    with torch.no_grad():
-        encoded = tokenizer(words, padding=True, truncation=True, return_tensors="pt")
-        model_output = model(**encoded)
-        embeddings = model_output.last_hidden_state.mean(dim=1)
-    return embeddings.numpy()
-
-# ----------------------------
-# INFO PAGE
-# ----------------------------
-def info_page():
-    st.markdown("""
-    ## about this demo
-    embeddings are a way to turn words or sentences into lists of numbers.  
-    these numbers are arranged so that similar meanings are placed close together in this space.  
-    this makes it possible to compare meanings with math.  
-    here you can see how different words are mapped into a 2d or 3d space,  
-    so related words appear near each other.
-    """)
-    st.page_link("?", label="⬅ back to demo")
-
-# ----------------------------
-# MAIN DEMO
-# ----------------------------
-def main_page():
-    # top controls
-    col1, col2, col3 = st.columns([1.5, 1, 1])
-    with col1:
-        dataset_name = st.selectbox("dataset", list(DATASETS.keys()))
-    with col2:
-        embed_choice = st.selectbox("embedding model", list(EMBED_MODELS.keys()))
-    with col3:
-        proj_mode = st.radio("projection", ["2d", "3d"], horizontal=True)
-
-    # show dataset words
-    words = DATASETS[dataset_name]
-    st.text_area("dataset words", "\n".join(words), height=120)
-
-    # embedding
-    tokenizer, model = load_model(EMBED_MODELS[embed_choice])
-    vecs = embed_words(tokenizer, model, words)
-
-    # project
-    dims = 2 if proj_mode == "2d" else 3
-    if vecs.shape[1] > dims:
-        vecs = PCA(n_components=dims).fit_transform(vecs)
-
-    # plot
-    fig = go.Figure()
-    if dims == 3:
-        fig.add_trace(go.Scatter3d(
-            x=vecs[:,0], y=vecs[:,1], z=vecs[:,2],
-            mode='markers+text',
-            text=words,
-            textposition="top center"
-        ))
-        # cube faces
-        cube_faces = [
-            dict(type="mesh3d",
-                 x=[-1,1,1,-1], y=[-1,-1,1,1], z=[1,1,1,1],
-                 color='rgba(255,182,193,1)'),
-            dict(type="mesh3d",
-                 x=[-1,1,1,-1], y=[-1,-1,1,1], z=[-1,-1,-1,-1],
-                 color='rgba(173,216,230,1)')
-        ]
-        for face in cube_faces:
-            fig.add_trace(go.Mesh3d(**face))
-        fig.update_layout(scene_camera=dict(
-            eye=dict(x=1.5, y=1.5, z=1.5)
-        ))
-        if st.button("rotate"):
-            fig.update_layout(scene_camera=dict(
-                eye=dict(x=1.5, y=1.5, z=1.5)
-            ), transition=dict(duration=2000), uirevision=True)
-    else:
-        fig.add_trace(go.Scatter(
-            x=vecs[:,0], y=vecs[:,1],
-            mode='markers+text',
-            text=words,
-            textposition="top center"
-        ))
-    st.plotly_chart(fig, use_container_width=True)
-
-# ----------------------------
-# ROUTER
-# ----------------------------
-params = st.query_params
-if params.get("page") == "info":
-    info_page()
-else:
-    st.page_link("?page=info", label="ℹ info")
-    main_page()
- cube faces
-# - Smooth rotation that STARTS from the CURRENT manual view (captured via relayout)
-# - Continuous rotation until toggled off
-
 import time
 import random
 import numpy as np
@@ -165,65 +8,70 @@ from sklearn.decomposition import PCA
 import torch
 from transformers import AutoTokenizer, AutoModel
 
-# Optional but recommended: capture Plotly relayout (camera) to start rotation from manual view
-# pip install streamlit-plotly-events
-try:
-    from streamlit_plotly_events import plotly_events
-    HAVE_EVENTS = True
-except Exception:
-    HAVE_EVENTS = False
-
 st.set_page_config(page_title="Embedding Demo", layout="wide")
 
-# -----------------------
-# BASE DATASETS
-# -----------------------
+# ----------------------------
+# BASE DATASETS (lowercase)
+# ----------------------------
 DATASETS = {
-    "sports": ["Soccer","Basketball","Tennis","Baseball","Golf","Swimming","Cycling","Running","Volleyball","Rugby",
-               "Boxing","Skiing","Surfing","Skateboarding","Hiking","Rowing","Fencing","Gymnastics","Badminton","Cricket","Wrestling"],
-    "countries": ["Germany","France","Italy","Spain","Portugal","Netherlands","Belgium","Sweden","Norway","Denmark",
-                  "Finland","Poland","Austria","Switzerland","Greece","Turkey","Ireland","Hungary","Czechia","Slovakia","Slovenia"],
-    "animals": ["Cat","Dog","Elephant","Tiger","Lion","Horse","Cow","Sheep","Goat","Monkey","Bear","Wolf","Deer","Kangaroo",
-                "Panda","Rabbit","Fox","Giraffe","Zebra","Hippopotamus","Crocodile"],
-    "furniture": ["Armchair","Sofa","Dining table","Coffee table","Bookshelf","Bed","Wardrobe","Desk","Office chair","Dresser",
-                  "Nightstand","Side table","TV stand","Loveseat","Chaise lounge","Bench","Hutch","Kitchen island","Futon","Recliner",
-                  "Ottoman","Console table","Vanity","Buffet","Sectional sofa"],
-    "actor": ["Leonardo DiCaprio","Brad Pitt","Tom Hanks","Johnny Depp","Robert De Niro","Al Pacino","Morgan Freeman","Denzel Washington","Tom Cruise",
-              "Will Smith","Matt Damon","Harrison Ford","George Clooney","Christian Bale","Keanu Reeves","Russell Crowe","Hugh Jackman",
-              "Samuel L. Jackson","Anthony Hopkins","Mark Wahlberg","Edward Norton"],
-    "rock group": ["Queen","The Beatles","Rolling Stones","Pink Floyd","Led Zeppelin","AC/DC","Nirvana","Metallica","U2","The Who",
-                   "Guns N' Roses","Coldplay","Red Hot Chili Peppers","The Doors","Radiohead","Pearl Jam","The Police","Aerosmith","Deep Purple","Oasis","Foo Fighters"],
+    "countries": [
+        "germany","france","italy","spain","portugal","poland","netherlands","belgium",
+        "austria","switzerland","greece","norway","sweden","finland","denmark","ireland",
+        "hungary","czechia","slovakia","slovenia","iceland","estonia","latvia","lithuania","romania"
+    ],
+    "animals": [
+        "cat","dog","lion","tiger","bear","wolf","fox","eagle","shark","whale",
+        "zebra","giraffe","elephant","hippopotamus","rhinoceros","kangaroo","panda","otter","seal","dolphin",
+        "chimpanzee","gorilla","leopard","cheetah","lynx"
+    ],
+    "furniture": [
+        "armchair","sofa","dining table","coffee table","bookshelf","bed","wardrobe","desk","office chair","dresser",
+        "nightstand","side table","tv stand","loveseat","chaise lounge","bench","hutch","kitchen island","futon","recliner",
+        "ottoman","console table","vanity","buffet","sectional sofa"
+    ],
+    "actors": [
+        "brad pitt","angelina jolie","meryl streep","leonardo dicaprio","tom hanks","scarlett johansson","robert de niro",
+        "natalie portman","matt damon","cate blanchett","johnny depp","keanu reeves","hugh jackman","emma stone","ryan gosling",
+        "jennifer lawrence","christian bale","charlize theron","will smith","anne hathaway","denzel washington","morgan freeman",
+        "julia roberts","george clooney","kate winslet"
+    ],
+    "rock group": [
+        "the beatles","rolling stones","pink floyd","queen","led zeppelin","u2","ac/dc","nirvana","radiohead","metallica",
+        "guns n' roses","red hot chili peppers","coldplay","pearl jam","the police","aerosmith","green day","foo fighters",
+        "the doors","bon jovi","deep purple","the who","the kinks","fleetwood mac","the beach boys"
+    ],
+    "sports": [
+        "soccer","basketball","tennis","baseball","golf","swimming","cycling","running","volleyball","rugby",
+        "boxing","skiing","snowboarding","surfing","skateboarding","karate","judo","fencing","rowing","badminton",
+        "cricket","table tennis","gymnastics","hockey","climbing"
+    ]
 }
 
-# -----------------------
-# CREATE 3 RANDOM MIXED SETS ON STARTUP
-# Each: pick 3 distinct source sets; 7 items from each (21 total)
-# Name: "set1/set2/set3" (lowercase)
-# -----------------------
-def create_random_mixed_sets(base_dict, n_sets=3):
-    base_keys = list(base_dict.keys())
+# ----------------------------
+# RANDOM MIXED SETS (once per session)
+# ----------------------------
+def make_random_mixed_sets(base: dict, n_sets: int = 3) -> dict:
+    keys = list(base.keys())
     mixed = {}
     for _ in range(n_sets):
-        sources = random.sample(base_keys, 3)
+        sources = random.sample(keys, 3)
         items = []
         for s in sources:
-            # Guard: some sets might have fewer than 7 (we do min)
-            k = min(7, len(base_dict[s]))
-            items.extend(random.sample(base_dict[s], k))
-        name = "/".join(sources).lower()
-        mixed[name] = items[:21]
+            take = min(7, len(base[s]))
+            items.extend(random.sample(base[s], take))
+        mixed_name = "/".join(sources).lower()
+        mixed[mixed_name] = items[:21]
     return mixed
 
-# Only generate once per process
-if "mixed_inserted" not in st.session_state:
-    DATASETS.update(create_random_mixed_sets(DATASETS, n_sets=3))
-    st.session_state.mixed_inserted = True
+if "mixed_added" not in st.session_state:
+    DATASETS.update(make_random_mixed_sets(DATASETS, 3))
+    st.session_state.mixed_added = True
 
-# -----------------------
+# ----------------------------
 # MODELS (transformers)
-# -----------------------
+# ----------------------------
 EMBED_MODELS = {
-    "all-MiniLM-L6-v2 (384d)": "sentence-transformers/all-MiniLM-L6-v2",
+    "all-minilm-l6-v2 (384d)": "sentence-transformers/all-MiniLM-L6-v2",
     "all-mpnet-base-v2 (768d)": "sentence-transformers/all-mpnet-base-v2",
     "all-roberta-large-v1 (1024d)": "sentence-transformers/all-roberta-large-v1",
 }
@@ -242,222 +90,180 @@ def embed_texts(model_name: str, texts_tuple: tuple):
     with torch.no_grad():
         inputs = tokenizer(texts, padding=True, truncation=True, return_tensors="pt")
         outputs = model(**inputs)
-        # Mean pooling with attention mask
         token_embeddings = outputs.last_hidden_state  # (B,T,H)
         mask = inputs["attention_mask"].unsqueeze(-1).type_as(token_embeddings)
         summed = (token_embeddings * mask).sum(dim=1)
         counts = mask.sum(dim=1).clamp(min=1e-9)
-        embeddings = summed / counts
+        embeddings = summed / counts  # mean pooling
     return embeddings.cpu().numpy()
 
-# -----------------------
-# STATE FOR CAMERA + ROTATION
-# -----------------------
-if "live_camera" not in st.session_state:
-    st.session_state.live_camera = {"eye": {"x": 1.8, "y": 0.0, "z": 1.0}, "projection": {"type": "perspective"}}
-
-if "rotate_on" not in st.session_state:
-    st.session_state.rotate_on = False
-
-if "dataset_select" not in st.session_state:
-    st.session_state.dataset_select = "furniture"
-
-if "model_name" not in st.session_state:
-    st.session_state.model_name = list(EMBED_MODELS.values())[0]
-
-if "proj_mode" not in st.session_state:
-    st.session_state.proj_mode = "3D"
-
-# -----------------------
-# ROUTING: info or demo
-# -----------------------
-params = st.query_params
-page = params.get("page", ["demo"])[0]
+# ----------------------------
+# STATE: camera + rotation
+# ----------------------------
+if "camera_eye" not in st.session_state:
+    st.session_state.camera_eye = {"x": 1.6, "y": 1.6, "z": 1.2}
+if "spinning" not in st.session_state:
+    st.session_state.spinning = False
+if "angle_rad" not in st.session_state:
+    # derive from eye.x, eye.y
+    e = st.session_state.camera_eye
+    st.session_state.angle_rad = float(np.arctan2(e["y"], e["x"]))
+
+def update_eye_from_angle(angle_rad: float, radius: float, z: float):
+    return {"x": radius * np.cos(angle_rad), "y": radius * np.sin(angle_rad), "z": z}
 
-def set_page(name: str):
-    st.query_params["page"] = name
+# ----------------------------
+# NAVIGATION via st.query_params
+# ----------------------------
+def goto(page: str):
+    st.query_params["page"] = page
     st.rerun()
 
-# -----------------------
+page = st.query_params.get("page", ["demo"])[0]
+
+# ----------------------------
 # INFO PAGE
-# -----------------------
-def show_info():
-    st.title("ℹ About this demo")
-    st.write(
-        """
-**Embeddings** turn words (or longer text) into numerical vectors.  
-In this vector space, **semantically related** items end up **near** each other.  
-That property makes embeddings useful for:
-- semantic search & retrieval
-- clustering & topic discovery
-- recommendation & deduplication
+# ----------------------------
+def info_page():
+    st.title("ℹ about this demo")
+    st.write("""
+**embeddings** turn words (or longer text) into numerical vectors.  
+in this vector space, **semantically related** items end up **near** each other.  
+
+why this is useful:
+- semantic search and retrieval
+- clustering and topic discovery
+- recommendations and deduplication
 - measuring similarity and analogies
 
-This demo embeds single words with a selectable model, reduces to 2D/3D with PCA,
+this demo embeds single words with a selectable model, reduces to 2d/3d with pca,
 and shows how related words cluster in the projected space.
-        """
-    )
-    if st.button("⬅ Back to demo"):
-        set_page("demo")
+    """.strip())
+    if st.button("⬅ back to demo"):
+        goto("demo")
 
-# -----------------------
+# ----------------------------
 # DEMO PAGE
-# -----------------------
-def show_demo():
-    # Header row: model selector (left), info button (middle), 2D/3D toggle (right)
-    h1, h2, h3 = st.columns([3, 1, 1])
-    with h1:
-        labels = list(EMBED_MODELS.keys())
-        name_map = EMBED_MODELS
-        # get current label from state value
-        rev = {v: k for k, v in name_map.items()}
-        current_label = rev.get(st.session_state.model_name, labels[0])
-        chosen_label = st.selectbox("Embedding model", labels, index=labels.index(current_label))
-        st.session_state.model_name = name_map[chosen_label]
-    with h2:
-        if st.button("ℹ Info"):
-            set_page("info")
-    with h3:
-        st.session_state.proj_mode = st.radio("", ["2D", "3D"], horizontal=True,
-                                              index=1 if st.session_state.proj_mode == "3D" else 0)
-
-    # Two-column layout: dataset+editor (left), plot (right)
-    left, right = st.columns([1, 3], gap="large")
-
-    with left:
-        ds_keys = list(DATASETS.keys())
-        st.session_state.dataset_select = st.selectbox(
-            "Dataset", ds_keys, index=ds_keys.index(st.session_state.dataset_select)
-        )
-        default_text = "\n".join(DATASETS[st.session_state.dataset_select])
-        user_text = st.text_area("Words (one per line)", value=default_text, height=300)
-        words = [w.strip() for w in user_text.split("\n") if w.strip()]
-        if len(words) < 3:
-            st.info("Enter at least three lines to project.")
-            st.stop()
-
-        # Rotate toggle + speed
-        r1, r2 = st.columns([1, 1])
-        with r1:
-            if st.button("⏯ Rotate"):
-                st.session_state.rotate_on = not st.session_state.rotate_on
-        with r2:
-            speed = st.slider("Speed (deg/frame)", 1, 10, 3, help="Rotation speed in degrees per frame (3 is smooth).")
-
-    with right:
-        # Embed (cached) and PCA
-        embs = embed_texts(st.session_state.model_name, tuple(words))
-        n_comp = 3 if st.session_state.proj_mode == "3D" else 2
-        coords = PCA(n_components=n_comp).fit_transform(embs)
-
-        # Title centered & blue
-        title_html = f"<b style='color:#1f77b4; font-size:2.2rem;'>{st.session_state.dataset_select}</b>"
-
-        # Build figure
-        if st.session_state.proj_mode == "3D":
-            eye = st.session_state.live_camera.get("eye", {"x": 1.8, "y": 0.0, "z": 1.0})
-            fig = go.Figure(
-                data=[go.Scatter3d(
-                    x=coords[:, 0], y=coords[:, 1], z=coords[:, 2],
-                    mode="markers+text", text=words, textposition="top center",
-                    marker=dict(size=6),
-                )],
-                layout=go.Layout(
-                    title=dict(text=title_html, x=0.5, xanchor="center", yanchor="top",
-                               font=dict(size=32, color="#1f77b4")),
-                    scene=dict(
-                        camera=dict(eye=eye, projection=dict(type="perspective")),
-                        xaxis=dict(showbackground=True, backgroundcolor="rgba(255, 230, 230, 1)"),
-                        yaxis=dict(showbackground=True, backgroundcolor="rgba(230, 255, 230, 1)"),
-                        zaxis=dict(showbackground=True, backgroundcolor="rgba(230, 230, 255, 1)"),
-                    ),
-                    margin=dict(l=0, r=0, b=0, t=60),
-                    uirevision="keep",  # keep interactions across reruns
-                )
-            )
-        else:
-            fig = go.Figure(
-                data=[go.Scatter(
-                    x=coords[:, 0], y=coords[:, 1],
-                    mode="markers+text", text=words, textposition="top center",
-                    marker=dict(size=10),
-                )],
-                layout=go.Layout(
-                    title=dict(text=title_html, x=0.5, xanchor="center", yanchor="top",
-                               font=dict(size=32, color="#1f77b4")),
-                    xaxis=dict(title="PC1"),
-                    yaxis=dict(title="PC2", scaleanchor="x", scaleratio=1),
-                    margin=dict(l=0, r=0, b=0, t=60),
-                )
-            )
+# ----------------------------
+def demo_page():
+    # top row: dataset, model + 2d/3d, info button
+    c1, c2, c3 = st.columns([2, 2, 1])
+    with c1:
+        ds_names = list(DATASETS.keys())
+        dataset_name = st.selectbox("dataset", ds_names, index=ds_names.index("furniture") if "furniture" in ds_names else 0)
+    with c2:
+        cc1, cc2 = st.columns([2, 1])
+        with cc1:
+            model_label = st.selectbox("embedding model", list(EMBED_MODELS.keys()))
+            model_name = EMBED_MODELS[model_label]
+        with cc2:
+            proj_mode = st.radio("projection", ["2d", "3d"], horizontal=True)
+    with c3:
+        if st.button("ℹ info"):
+            goto("info")
 
-        # Use a placeholder so we can update the figure in-place during rotation
-        ph = st.empty()
+    words = DATASETS[dataset_name]
+    st.text_area("dataset words", "\n".join(words), height=160)
 
-        # First render
-        if HAVE_EVENTS and st.session_state.proj_mode == "3D":
-            # Capture relayout to update live camera if user moved it before hitting rotate
-            _ = plotly_events(
-                fig, events=["relayout"], select_event=False, click_event=False, hover_event=False,
-                override_width="100%", override_height=None, key="plot3d"
+    # Embed + PCA
+    embs = embed_texts(model_name, tuple(words))
+    if proj_mode == "2d":
+        coords = PCA(n_components=2).fit_transform(embs)
+    else:
+        coords = PCA(n_components=3).fit_transform(embs)
+
+    title_html = f"<b style='color:#1f77b4; font-size:2.0rem;'>{dataset_name}</b>"
+
+    if proj_mode == "3d":
+        # compute radius from current eye, keep same z
+        eye = st.session_state.camera_eye
+        radius = float(np.sqrt(eye["x"]**2 + eye["y"]**2)) or 1.6
+        z_eye = float(eye["z"])
+
+        fig = go.Figure(
+            data=[go.Scatter3d(
+                x=coords[:, 0], y=coords[:, 1], z=coords[:, 2],
+                mode="markers+text", text=words, textposition="top center",
+                marker=dict(size=6),
+            )],
+            layout=go.Layout(
+                title=dict(text=title_html, x=0.5, xanchor="center", yanchor="top",
+                           font=dict(size=30, color="#1f77b4")),
+                scene=dict(
+                    camera=dict(eye=eye, projection=dict(type="perspective")),
+                    xaxis=dict(showbackground=True, backgroundcolor="rgba(255, 230, 230, 1)"),
+                    yaxis=dict(showbackground=True, backgroundcolor="rgba(230, 255, 230, 1)"),
+                    zaxis=dict(showbackground=True, backgroundcolor="rgba(230, 230, 255, 1)"),
+                ),
+                margin=dict(l=0, r=0, b=0, t=60),
+                uirevision="keep",
             )
-            # Update stored camera from relayout payload if present
-            rel_key = "plotly_relayout-data-plot3d"
-            rel = st.session_state.get(rel_key)
-            if isinstance(rel, dict):
-                cam_update = rel.get("scene.camera") or {}
-                if "eye" in cam_update:
-                    st.session_state.live_camera = {
-                        "eye": cam_update["eye"],
-                        "projection": {"type": "perspective"}
-                    }
-                else:
-                    # Sometimes relayout sends separate eye components
-                    keys = ["scene.camera.eye.x", "scene.camera.eye.y", "scene.camera.eye.z"]
-                    if all(k in rel for k in keys):
-                        st.session_state.live_camera = {
-                            "eye": {"x": rel[keys[0]], "y": rel[keys[1]], "z": rel[keys[2]]},
-                            "projection": {"type": "perspective"}
-                        }
-        else:
-            ph.plotly_chart(fig, use_container_width=True)
-
-        # Continuous rotation loop (only in 3D and when rotate_on is True)
-        if st.session_state.proj_mode == "3D" and st.session_state.rotate_on:
-            # Start from the CURRENT live camera (which includes any manual rotation)
-            eye = st.session_state.live_camera["eye"]
-            r = max(1e-6, float(np.sqrt(eye["x"]**2 + eye["y"]**2)))
-            z_eye = float(eye["z"])
-            # Current angle in radians based on x,y
-            angle = float(np.arctan2(eye["y"], eye["x"]))
-
-            # Render a batch of frames, then rerun to keep UI responsive
-            frames = 180  # ~6 seconds at 33ms per frame
-            step = np.deg2rad(speed)
-
-            for _ in range(frames):
-                # Update angle and camera eye
-                angle += step
-                new_eye = {"x": r * np.cos(angle), "y": r * np.sin(angle), "z": z_eye}
-                st.session_state.live_camera = {"eye": new_eye, "projection": {"type": "perspective"}}
-                fig.update_layout(scene_camera=st.session_state.live_camera)
-
-                # Render updated frame
-                ph.plotly_chart(fig, use_container_width=True)
-                time.sleep(0.033)  # ~30 FPS
+        )
 
-                # If user toggled rotation off during this batch, break early
-                if not st.session_state.rotate_on:
+        # Controls under the plot: Start/Stop rotation
+        b1, b2 = st.columns([1, 1])
+        with b1:
+            start_clicked = st.button("▶ start rotation", disabled=st.session_state.spinning)
+        with b2:
+            stop_clicked = st.button("⏹ stop rotation", disabled=not st.session_state.spinning)
+
+        # If start pressed: turn on spinner and initialize angle from current stored eye
+        if start_clicked:
+            st.session_state.spinning = True
+            # start from stored angle (not capturing manual camera — simple approach)
+            st.session_state.angle_rad = float(np.arctan2(eye["y"], eye["x"]))
+            # fall through to loop below (this turn will render once, then continue)
+
+        # If stop pressed: turn off spinner (and keep stop disabled after)
+        if stop_clicked:
+            st.session_state.spinning = False
+
+        # Live render placeholder
+        placeholder = st.empty()
+
+        # First draw (static) before any loop
+        placeholder.plotly_chart(fig, use_container_width=True)
+
+        # Continuous rotation loop while spinning
+        if st.session_state.spinning:
+            # one "batch" of frames, then rerun to keep UI responsive
+            steps_per_batch = 120
+            step = np.deg2rad(3)  # 3 degrees per frame ~ smooth
+            for _ in range(steps_per_batch):
+                if not st.session_state.spinning:
                     break
+                st.session_state.angle_rad += step
+                new_eye = update_eye_from_angle(st.session_state.angle_rad, radius, z_eye)
+                st.session_state.camera_eye = new_eye
+                fig.update_layout(scene_camera=dict(eye=new_eye, projection=dict(type="perspective")))
+                placeholder.plotly_chart(fig, use_container_width=True)
+                time.sleep(0.033)  # ~30 FPS
 
-            # If still on after this batch, trigger another rerun to continue rotating
-            if st.session_state.rotate_on:
+            # If still spinning after this batch, rerun to keep going
+            if st.session_state.spinning:
                 st.rerun()
 
-# -----------------------
+    else:
+        fig = go.Figure(
+            data=[go.Scatter(
+                x=coords[:, 0], y=coords[:, 1],
+                mode="markers+text", text=words, textposition="top center",
+                marker=dict(size=9),
+            )],
+            layout=go.Layout(
+                title=dict(text=title_html, x=0.5, xanchor="center", yanchor="top",
+                           font=dict(size=30, color="#1f77b4")),
+                xaxis=dict(title="PC1"),
+                yaxis=dict(title="PC2", scaleanchor="x", scaleratio=1),
+                margin=dict(l=0, r=0, b=0, t=60),
+            )
+        )
+        st.plotly_chart(fig, use_container_width=True)
+
+# ----------------------------
 # ROUTER
-# -----------------------
+# ----------------------------
 if page == "info":
-    show_info()
+    info_page()
 else:
-    show_demo()
+    demo_page()