Deploy MindVisualizer API

Dockerfile

@@ -0,0 +1,17 @@
+FROM python:3.11-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+ENV MINDVIS_REPO=/app/mindVisualizer
+
+WORKDIR /app/api
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY app.py .
+COPY mindVisualizer /app/mindVisualizer
+
+EXPOSE 7860
+
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,10 +1,47 @@
 ---
-title: Mindvisualizer Api
-emoji: 😻
-colorFrom: gray
-colorTo: pink
+title: MindVisualizer API
 sdk: docker
+app_port: 7860
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# MindVisualizer Python API
+
+Small FastAPI adapter for the hosted web page.
+
+The GitHub Pages frontend renders particles locally. This backend is only for algorithm-sensitive operations:
+
+- recomputing probe trajectories with the original Python `TriLinearSampler`
+- mapping a trajectory to ROI vectors with the original `ManifoldToROIKNN`
+- building the original `ROIFlowAnalyzer` context
+- optionally calling the original `ROIFlowLLM` if `OPENAI_API_KEY` is configured
+
+## Cheapest hosting shape
+
+Use a free Python container host and keep the service public:
+
+1. Bundle the minimal `mindVisualizer` source/data folder into the Space as `/app/mindVisualizer`.
+2. Deploy this directory as a Docker/FastAPI service.
+3. Set `MINDVIS_REPO=/app/mindVisualizer`.
+4. Set `CORS_ORIGINS=https://pixedar.github.io,http://localhost:3000`.
+5. In the GitHub Pages build, set `NEXT_PUBLIC_MINDVIS_API_URL=https://your-backend-url`.
+
+Do not install the full `mindVisualizer` `pyproject.toml` on a tiny free host; it pulls desktop/VTK dependencies. This adapter uses `PYTHONPATH` and installs only the packages needed for the API path.
+
+## Local run
+
+```bash
+cd backend/mindvis-api
+python -m venv .venv
+.venv\Scripts\activate
+pip install -r requirements.txt
+$env:MINDVIS_REPO="C:\Users\assas\PycharmProjects\mindVisualizer"
+uvicorn app:app --reload --port 7860
+```
+
+Then build/run the web page with:
+
+```bash
+$env:NEXT_PUBLIC_MINDVIS_API_URL="http://localhost:7860"
+pnpm dev
+```

app.py

@@ -0,0 +1,168 @@
+import json
+import os
+import sys
+from functools import lru_cache
+from pathlib import Path
+from typing import Literal
+
+import numpy as np
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel, Field
+
+
+FieldMode = Literal["mean", "gated", "mu1", "mu2"]
+
+
+class TrajectoryRequest(BaseModel):
+    seed: list[float] = Field(default_factory=lambda: [0.5, 0.5, 0.5], min_length=3, max_length=3)
+    fieldMode: FieldMode = "gated"
+    steps: int = Field(default=220, ge=8, le=1200)
+    dt: float = Field(default=0.018, gt=0, le=0.1)
+    speedScale: float = Field(default=0.48, gt=0, le=4)
+
+
+class ExplainRequest(BaseModel):
+    trajectory: list[list[float]] = Field(min_length=2)
+    fieldMode: FieldMode = "gated"
+    callLlm: bool = True
+
+
+def mindvis_repo() -> Path:
+    repo = Path(os.environ.get("MINDVIS_REPO", "/app/mindVisualizer")).resolve()
+    if not repo.exists():
+        raise RuntimeError(f"MINDVIS_REPO does not exist: {repo}")
+    if str(repo) not in sys.path:
+        sys.path.insert(0, str(repo))
+    return repo
+
+
+@lru_cache(maxsize=1)
+def services():
+    repo = mindvis_repo()
+
+    from src.field_loader import TriLinearSampler, load_field
+    from src.roi_flow import ManifoldToROIKNN, ROIFlowAnalyzer
+
+    data = repo / "data"
+    flow = load_field(data / "roi_flow" / "mdn_universal_raw_grid64_meta.json")
+    mean = flow["mean"]
+    mu1 = flow["mus"][0]
+    mu2 = flow["mus"][1]
+    pi = flow["pi"]
+    gated = np.where(np.argmax(pi, axis=-1)[..., None] == 0, mu1, mu2).astype(np.float32)
+
+    samplers = {
+        "mean": TriLinearSampler(mean, flow["amin"], flow["amax"]),
+        "gated": TriLinearSampler(gated, flow["amin"], flow["amax"]),
+        "mu1": TriLinearSampler(mu1, flow["amin"], flow["amax"]),
+        "mu2": TriLinearSampler(mu2, flow["amin"], flow["amax"]),
+    }
+
+    embed = np.load(data / "roi_flow" / "probe_embed.npy").astype(np.float32)
+    roi = np.load(data / "roi_flow" / "probe_roi.npy").astype(np.float32)
+    centers = np.load(data / "roi_flow" / "probe_roi_centers.npy").astype(np.float32)
+    structures = json.loads((data / "structures.json").read_text(encoding="utf-8"))
+
+    names = []
+    for idx in range(roi.shape[1]):
+        item = structures[idx] if idx < len(structures) else {}
+        names.append(item.get("name") or item.get("acronym") or f"ROI {idx + 1}")
+
+    mapper = ManifoldToROIKNN(embed, roi, k=256)
+    analyzer = ROIFlowAnalyzer(names, centers[: len(names)])
+
+    return {
+        "amin": flow["amin"],
+        "amax": flow["amax"],
+        "span": flow["amax"] - flow["amin"],
+        "samplers": samplers,
+        "mapper": mapper,
+        "analyzer": analyzer,
+    }
+
+
+app = FastAPI(title="MindVisualizer API", version="0.1.0")
+
+origins = [origin.strip() for origin in os.environ.get("CORS_ORIGINS", "*").split(",") if origin.strip()]
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=origins,
+    allow_methods=["GET", "POST", "OPTIONS"],
+    allow_headers=["*"],
+)
+
+
+@app.get("/health")
+def health():
+    try:
+        svc = services()
+        return {"ok": True, "fieldMin": svc["amin"].tolist(), "fieldMax": svc["amax"].tolist()}
+    except Exception as exc:
+        raise HTTPException(status_code=503, detail=str(exc)) from exc
+
+
+@app.post("/api/mindvis/trajectory")
+def trajectory(req: TrajectoryRequest):
+    svc = services()
+    path = integrate_path(req.seed, req.fieldMode, req.steps, req.dt, req.speedScale)
+    return {
+        "fieldMode": req.fieldMode,
+        "trajectory": normalized(path, svc["amin"], svc["span"]).tolist(),
+    }
+
+
+@app.post("/api/mindvis/explain")
+def explain(req: ExplainRequest):
+    svc = services()
+    traj = np.asarray(req.trajectory, dtype=np.float32)
+    if traj.ndim != 2 or traj.shape[1] != 3:
+        raise HTTPException(status_code=400, detail="trajectory must be an array of [x,y,z] points")
+
+    world = denormalized(np.clip(traj, 0.0, 1.0), svc["amin"], svc["span"])
+    mapper = svc["mapper"]
+    analyzer = svc["analyzer"]
+    start_roi = mapper.query(world[0])
+    end_roi = mapper.query(world[-1])
+    delta = analyzer.compute_delta(start_roi, end_roi)
+    context = analyzer.build_llm_context(delta)
+
+    text = ""
+    if req.callLlm and os.environ.get("OPENAI_API_KEY"):
+        from src.roi_flow import ROIFlowLLM
+
+        text = ROIFlowLLM(debug=False).interpret_roi_flow(context)
+
+    if not text:
+        analysis = analyzer.analyze_flow_pattern(delta)
+        text = (
+            f"Pattern: {analysis['pattern_type']}. "
+            f"Bulk direction: {analysis['bulk_direction']}. "
+            f"Positive ROIs: {analysis['n_significant_positive']}; "
+            f"negative ROIs: {analysis['n_significant_negative']}."
+        )
+
+    return {"text": text, "context": context}
+
+
+def integrate_path(seed: list[float], field_mode: FieldMode, steps: int, dt: float, speed_scale: float) -> np.ndarray:
+    svc = services()
+    p = denormalized(np.asarray(seed[:3], dtype=np.float32)[None, :], svc["amin"], svc["span"])
+    sampler = svc["samplers"][field_mode]
+    path = np.empty((steps, 3), dtype=np.float32)
+
+    for idx in range(steps):
+        path[idx] = p[0]
+        v = sampler.sample_vec(p)
+        p = p + v * (dt * speed_scale)
+        p = ((p - svc["amin"]) % svc["span"]) + svc["amin"]
+
+    return path
+
+
+def denormalized(points: np.ndarray, amin: np.ndarray, span: np.ndarray) -> np.ndarray:
+    return points.astype(np.float32) * span[None, :] + amin[None, :]
+
+
+def normalized(points: np.ndarray, amin: np.ndarray, span: np.ndarray) -> np.ndarray:
+    return (points.astype(np.float32) - amin[None, :]) / span[None, :]

mindVisualizer/data/roi_flow/mdn_training_all_points.npy

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

mindVisualizer/data/roi_flow/mdn_universal_all_grid64_entropy.bin

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

mindVisualizer/data/roi_flow/mdn_universal_all_grid64_mean_xyz3.bin

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

mindVisualizer/data/roi_flow/mdn_universal_all_grid64_mu1_xyz3.bin

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

mindVisualizer/data/roi_flow/mdn_universal_all_grid64_mu2_xyz3.bin

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

mindVisualizer/data/roi_flow/mdn_universal_all_grid64_pi.bin

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

mindVisualizer/data/roi_flow/mdn_universal_raw_grid64_meta.json

@@ -0,0 +1 @@
+{"grid":64,"axis_min":[-0.5743489265441895,-0.18553070724010468,-0.38263601064682007],"axis_max":[0.3224758803844452,0.597403883934021,0.37152180075645447],"files":{"mean_xyz3":"mdn_universal_all_grid64_mean_xyz3.bin","mu1_xyz3":"mdn_universal_all_grid64_mu1_xyz3.bin","mu2_xyz3":"mdn_universal_all_grid64_mu2_xyz3.bin","pi":"mdn_universal_all_grid64_pi.bin","entropy":"mdn_universal_all_grid64_entropy.bin"},"training_points_npy":"mdn_training_all_points.npy","dtype":"float32","layout":"C-order (x, y, z, 3) for *_xyz3; (x, y, z) for scalars","endianness":"little","mixture_mean_field":true,"model":{"hidden":200,"iters":35045,"keep_q":1.0,"min_frac":1.0},"mdn_source":"universal_all","bounds_mode":"full","bounds_pad":0.0}

mindVisualizer/data/roi_flow/probe_embed.npy

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

mindVisualizer/data/roi_flow/probe_roi.npy

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

mindVisualizer/data/roi_flow/probe_roi_centers.npy

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

mindVisualizer/data/structures.json

@@ -0,0 +1 @@
+[{"name": "neural plate", "acronym": "root", "id": 10153, "rgb_triplet": [215, 216, 216], "structure_id_path": [10153]}, {"name": "neural tube", "acronym": "NT", "id": 10154, "rgb_triplet": [208, 208, 209], "structure_id_path": [10153, 10154]}, {"name": "brain", "acronym": "Br", "id": 10155, "rgb_triplet": [224, 224, 224], "structure_id_path": [10153, 10154, 10155]}, {"name": "forebrain (prosencephalon)", "acronym": "F", "id": 10156, "rgb_triplet": [235, 214, 208], "structure_id_path": [10153, 10154, 10155, 10156]}, {"name": "gray matter of forebrain", "acronym": "FGM", "id": 10157, "rgb_triplet": [235, 214, 208], "structure_id_path": [10153, 10154, 10155, 10156, 10157]}, {"name": "telencephalon", "acronym": "Tel", "id": 10158, "rgb_triplet": [235, 214, 208], "structure_id_path": [10153, 10154, 10155, 10156, 10157, 10158]}, {"name": "cerebral cortex", "acronym": "Cx", "id": 10159, "rgb_triplet": [233, 204, 194], "structure_id_path": [10153, 10154, 10155, 10156, 10157, 10158, 10159]}, {"name": "periallocortex", "acronym": "PACx", "id": 10313, "rgb_triplet": [220, 208, 198], "structure_id_path": [10153, 10154, 10155, 10156, 10157, 10158, 10159, 10313]}, {"name": "peripaleocortex", "acronym": "PPCx", "id": 10327, "rgb_triplet": [203, 183, 168], "structure_id_path": [10153, 10154, 10155, 10156, 10157, 10158, 10159, 10313, 10327]}, {"name": "frontal agranular insular cortex (area FI)", "acronym": "FI", "id": 10329, "rgb_triplet": [193, 166, 143], "structure_id_path": [10153, 10154, 10155, 10156, 10157, 10158, 10159, 10313, 10327, 10329]}, {"name": "temporal agranular insular cortex (area TI)", "acronym": "TI", "id": 10330, "rgb_triplet": [181, 150, 127], "structure_id_path": [10153, 10154, 10155, 10156, 10157, 10158, 10159, 10313, 10327, 10330]}, {"name": "allocortex", "acronym": "ACx", "id": 10292, "rgb_triplet": [209, 206, 226], "structure_id_path": [10153, 10154, 10155, 10156, 10157, 10158, 10159, 10292]}, {"name": "paleocortex (semicortex)", "acronym": "PalCx", "id": 10306, "rgb_triplet": [191, 181, 213], "structure_id_path": [10153, 10154, 10155, 10156, 10157, 10158, 10159, 10292, 10306]}, {"name": "olfactory bulb", "acronym": "OB", "id": 10307, "rgb_triplet": [209, 206, 226], "structure_id_path": [10153, 10154, 10155, 10156, 10157, 10158, 10159, 10292, 10306, 10307]}, {"name": "anterior olfactory nucleus", "acronym": "AON", "id": 10308, "rgb_triplet": [170, 157, 198], "structure_id_path": [10153, 10154, 10155, 10156, 10157, 10158, 10159, 10292, 10306, 10308]}, {"name": "piriform cortex", "acronym": "Pir", "id": 10311, "rgb_triplet": [170, 157, 198], "structure_id_path": [10153, 10154, 10155, 10156, 10157, 10158, 10159, 10292, 10306, 10311]}, {"name": "cerebral nuclei", "acronym": "CN", "id": 10331, "rgb_triplet": [215, 233, 195], "structure_id_path": [10153, 10154, 10155, 10156, 10157, 10158, 10331]}, {"name": "amygdaloid complex", "acronym": "AMY", "id": 10361, "rgb_triplet": [201, 226, 177], "structure_id_path": [10153, 10154, 10155, 10156, 10157, 10158, 10331, 10361]}, {"name": "extended amygdala", "acronym": "EXA", "id": 10383, "rgb_triplet": [199, 228, 202], "structure_id_path": [10153, 10154, 10155, 10156, 10157, 10158, 10331, 10383]}, {"name": "bed nucleus of stria terminalis", "acronym": "BNST", "id": 10384, "rgb_triplet": [169, 215, 174], "structure_id_path": [10153, 10154, 10155, 10156, 10157, 10158, 10331, 10383, 10384]}, {"name": "basal nuclei (basal ganglia)", "acronym": "BN", "id": 10332, "rgb_triplet": [226, 234, 202], "structure_id_path": [10153, 10154, 10155, 10156, 10157, 10158, 10331, 10332]}, {"name": "striatum", "acronym": "STR", "id": 10333, "rgb_triplet": [193, 206, 167], "structure_id_path": [10153, 10154, 10155, 10156, 10157, 10158, 10331, 10332, 10333]}, {"name": "caudate nucleus", "acronym": "Ca", "id": 10334, "rgb_triplet": [153, 166, 119], "structure_id_path": [10153, 10154, 10155, 10156, 10157, 10158, 10331, 10332, 10333, 10334]}, {"name": "head of caudate", "acronym": "CaH", "id": 10335, "rgb_triplet": [145, 160, 110], "structure_id_path": [10153, 10154, 10155, 10156, 10157, 10158, 10331, 10332, 10333, 10334, 10335]}, {"name": "body of caudate", "acronym": "CaB", "id": 10336, "rgb_triplet": [153, 166, 119], "structure_id_path": [10153, 10154, 10155, 10156, 10157, 10158, 10331, 10332, 10333, 10334, 10336]}, {"name": "tail of caudate", "acronym": "CaT", "id": 10337, "rgb_triplet": [145, 160, 110], "structure_id_path": [10153, 10154, 10155, 10156, 10157, 10158, 10331, 10332, 10333, 10334, 10337]}, {"name": "putamen", "acronym": "Pu", "id": 10338, "rgb_triplet": [168, 180, 133], "structure_id_path": [10153, 10154, 10155, 10156, 10157, 10158, 10331, 10332, 10333, 10338]}, {"name": "nucleus accumbens", "acronym": "NAC", "id": 10339, "rgb_triplet": [145, 160, 110], "structure_id_path": [10153, 10154, 10155, 10156, 10157, 10158, 10331, 10332, 10333, 10339]}, {"name": "globus pallidus", "acronym": "GP", "id": 10342, "rgb_triplet": [215, 224, 191], "structure_id_path": [10153, 10154, 10155, 10156, 10157, 10158, 10331, 10332, 10342]}, {"name": "external segment of globus pallidus", "acronym": "GPe", "id": 10343, "rgb_triplet": [215, 224, 191], "structure_id_path": [10153, 10154, 10155, 10156, 10157, 10158, 10331, 10332, 10342, 10343]}, {"name": "internal segment of globus pallidus", "acronym": "GPi", "id": 10344, "rgb_triplet": [208, 217, 178], "structure_id_path": [10153, 10154, 10155, 10156, 10157, 10158, 10331, 10332, 10342, 10344]}, {"name": "claustrum", "acronym": "Cla", "id": 10346, "rgb_triplet": [170, 219, 206], "structure_id_path": [10153, 10154, 10155, 10156, 10157, 10158, 10331, 10346]}, {"name": "basal forebrain", "acronym": "BF", "id": 10349, "rgb_triplet": [221, 221, 175], "structure_id_path": [10153, 10154, 10155, 10156, 10157, 10158, 10331, 10349]}, {"name": "diencephalon", "acronym": "Die", "id": 10389, "rgb_triplet": [228, 204, 227], "structure_id_path": [10153, 10154, 10155, 10156, 10157, 10389]}, {"name": "thalamus", "acronym": "THM", "id": 10390, "rgb_triplet": [228, 204, 227], "structure_id_path": [10153, 10154, 10155, 10156, 10157, 10389, 10390]}, {"name": "subthalamus", "acronym": "SubTH", "id": 10465, "rgb_triplet": [221, 210, 230], "structure_id_path": [10153, 10154, 10155, 10156, 10157, 10389, 10465]}, {"name": "subthalamic nucleus", "acronym": "STH", "id": 10466, "rgb_triplet": [183, 153, 196], "structure_id_path": [10153, 10154, 10155, 10156, 10157, 10389, 10465, 10466]}, {"name": "hypothalamus", "acronym": "HTH", "id": 10467, "rgb_triplet": [228, 201, 217], "structure_id_path": [10153, 10154, 10155, 10156, 10157, 10389, 10467]}, {"name": "white matter of forebrain", "acronym": "FWM", "id": 10557, "rgb_triplet": [242, 241, 240], "structure_id_path": [10153, 10154, 10155, 10156, 10557]}, {"name": "ventricles of forebrain", "acronym": "FV", "id": 10595, "rgb_triplet": [35, 31, 32], "structure_id_path": [10153, 10154, 10155, 10156, 10595]}, {"name": "lateral ventricles", "acronym": "LV", "id": 10596, "rgb_triplet": [35, 31, 32], "structure_id_path": [10153, 10154, 10155, 10156, 10595, 10596]}, {"name": "anterior horn of lateral ventricle", "acronym": "aLV", "id": 10597, "rgb_triplet": [35, 31, 32], "structure_id_path": [10153, 10154, 10155, 10156, 10595, 10596, 10597]}, {"name": "body of lateral ventricle", "acronym": "bLV", "id": 10598, "rgb_triplet": [35, 31, 32], "structure_id_path": [10153, 10154, 10155, 10156, 10595, 10596, 10598]}, {"name": "atrium of lateral ventricle", "acronym": "xLV", "id": 266441657, "rgb_triplet": [35, 31, 32], "structure_id_path": [10153, 10154, 10155, 10156, 10595, 10596, 266441657]}, {"name": "posterior horn of lateral ventricle", "acronym": "pLV", "id": 10599, "rgb_triplet": [35, 31, 32], "structure_id_path": [10153, 10154, 10155, 10156, 10595, 10596, 10599]}, {"name": "inferior horn of lateral ventricle", "acronym": "iLV", "id": 10600, "rgb_triplet": [35, 31, 32], "structure_id_path": [10153, 10154, 10155, 10156, 10595, 10596, 10600]}, {"name": "third ventricle", "acronym": "3V", "id": 10602, "rgb_triplet": [35, 31, 32], "structure_id_path": [10153, 10154, 10155, 10156, 10595, 10602]}, {"name": "surface structures of forebrain", "acronym": "FSS", "id": 10609, "rgb_triplet": [200, 201, 202], "structure_id_path": [10153, 10154, 10155, 10156, 10609]}, {"name": "cerebral gyri and lobules", "acronym": "CeG", "id": 12112, "rgb_triplet": [223, 206, 206], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112]}, {"name": "frontal lobe", "acronym": "FroL", "id": 12113, "rgb_triplet": [242, 229, 187], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12113]}, {"name": "precentral gyrus", "acronym": "PrCG", "id": 12114, "rgb_triplet": [237, 207, 55], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12113, 12114]}, {"name": "superior frontal gyrus", "acronym": "SFG", "id": 12115, "rgb_triplet": [212, 178, 53], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12113, 12115]}, {"name": "middle frontal gyrus", "acronym": "MFG", "id": 12116, "rgb_triplet": [212, 178, 53], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12113, 12116]}, {"name": "inferior frontal gyrus", "acronym": "IFG", "id": 12117, "rgb_triplet": [194, 163, 53], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12113, 12117]}, {"name": "inferior frontal gyrus, triangular part", "acronym": "IFGtr", "id": 12118, "rgb_triplet": [194, 163, 53], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12113, 12117, 12118]}, {"name": "inferior frontal gyrus, opercular part", "acronym": "IFGop", "id": 12119, "rgb_triplet": [194, 163, 53], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12113, 12117, 12119]}, {"name": "gyrus rectus (straight gyrus)", "acronym": "ReG", "id": 12121, "rgb_triplet": [184, 162, 109], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12113, 12121]}, {"name": "medial orbital gyrus", "acronym": "MOrG", "id": 12122, "rgb_triplet": [202, 183, 129], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12113, 12122]}, {"name": "anterior intermediate orbital gyrus", "acronym": "AOrG", "id": 12123, "rgb_triplet": [202, 183, 129], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12113, 12123]}, {"name": "posterior intermediate orbital gyrus", "acronym": "POrG", "id": 12124, "rgb_triplet": [202, 183, 129], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12113, 12124]}, {"name": "lateral orbital gyrus", "acronym": "LOrG", "id": 12125, "rgb_triplet": [171, 145, 88], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12113, 12125]}, {"name": "paracentral lobule, rostral part", "acronym": "PCLr", "id": 12126, "rgb_triplet": [237, 207, 55], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12113, 12126]}, {"name": "paracingulate gyrus", "acronym": "PaCG", "id": 146034872, "rgb_triplet": [234, 166, 175], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12113, 146034872]}, {"name": "frontal operculum", "acronym": "FrO", "id": 12127, "rgb_triplet": [194, 163, 53], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12113, 12127]}, {"name": "rostral gyrus", "acronym": "RoG", "id": 146034876, "rgb_triplet": [184, 162, 109], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12113, 146034876]}, {"name": "lateral olfactory gyrus", "acronym": "LOG", "id": 13229, "rgb_triplet": [170, 157, 198], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12113, 13229]}, {"name": "frontomarginal gyrus", "acronym": "FMG", "id": 146034884, "rgb_triplet": [238, 207, 56], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12113, 146034884]}, {"name": "frontal pole", "acronym": "FP", "id": 146034888, "rgb_triplet": [234, 209, 128], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12113, 146034888]}, {"name": "parietal lobe", "acronym": "ParL", "id": 12131, "rgb_triplet": [240, 218, 190], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12131]}, {"name": "postcentral gyrus", "acronym": "PoCG", "id": 12132, "rgb_triplet": [236, 129, 59], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12131, 12132]}, {"name": "supraparietal lobule", "acronym": "SPL", "id": 12133, "rgb_triplet": [228, 156, 51], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12131, 12133]}, {"name": "inferior parietal lobule", "acronym": "IPL", "id": 12134, "rgb_triplet": [211, 142, 50], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12131, 12134]}, {"name": "supramarginal gyrus", "acronym": "SMG", "id": 12135, "rgb_triplet": [211, 142, 50], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12131, 12134, 12135]}, {"name": "angular gyrus", "acronym": "AnG", "id": 12136, "rgb_triplet": [211, 142, 50], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12131, 12134, 12136]}, {"name": "precuneus", "acronym": "PrCun", "id": 12137, "rgb_triplet": [228, 156, 51], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12131, 12137]}, {"name": "paracentral lobule, caudal part", "acronym": "PCLc", "id": 12138, "rgb_triplet": [228, 156, 51], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12131, 12138]}, {"name": "parietal operculum", "acronym": "PaO", "id": 13230, "rgb_triplet": [232, 175, 102], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12131, 13230]}, {"name": "temporal lobe", "acronym": "TemL", "id": 12139, "rgb_triplet": [235, 191, 208], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12139]}, {"name": "superior temporal gyrus", "acronym": "STG", "id": 12140, "rgb_triplet": [214, 112, 160], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12139, 12140]}, {"name": "middle temporal gyrus", "acronym": "MTG", "id": 12141, "rgb_triplet": [213, 92, 146], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12139, 12141]}, {"name": "inferior temporal gyrus", "acronym": "ITG", "id": 12142, "rgb_triplet": [213, 92, 146], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12139, 12142]}, {"name": "occipitotemporal (fusiform) gyrus, temporal part", "acronym": "FuGt", "id": 12143, "rgb_triplet": [213, 92, 146], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12139, 12143]}, {"name": "transverse temporal gyrus (Heschl's gyrus)", "acronym": "TTG", "id": 12144, "rgb_triplet": [214, 112, 160], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12139, 12144]}, {"name": "planum temporale", "acronym": "PLT", "id": 12145, "rgb_triplet": [214, 112, 160], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12139, 12145]}, {"name": "temporal pole", "acronym": "TP", "id": 12146, "rgb_triplet": [200, 83, 139], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12139, 12146]}, {"name": "planum polare", "acronym": "PLP", "id": 12147, "rgb_triplet": [214, 112, 160], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12139, 12147]}, {"name": "occipital lobe", "acronym": "OccL", "id": 12148, "rgb_triplet": [231, 172, 161], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12148]}, {"name": "occipital pole", "acronym": "OP", "id": 12149, "rgb_triplet": [193, 51, 49], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12148, 12149]}, {"name": "cuneus", "acronym": "Cun", "id": 12150, "rgb_triplet": [193, 51, 49], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12148, 12150]}, {"name": "lingual gyrus", "acronym": "LiG", "id": 12151, "rgb_triplet": [193, 51, 49], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12148, 12151]}, {"name": "occipitotemporal (fusiform) gyrus, occipital part", "acronym": "FuGo", "id": 12152, "rgb_triplet": [209, 77, 70], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12148, 12152]}, {"name": "inferior occipital gyrus", "acronym": "IOG", "id": 12153, "rgb_triplet": [209, 77, 70], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12148, 12153]}, {"name": "superior occipital gyrus", "acronym": "SOG", "id": 12154, "rgb_triplet": [209, 77, 70], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12148, 12154]}, {"name": "insular lobe", "acronym": "InL", "id": 12176, "rgb_triplet": [229, 171, 154], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12176]}, {"name": "long insular gyri", "acronym": "LIG", "id": 12177, "rgb_triplet": [196, 85, 57], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12176, 12177]}, {"name": "short insular gyri", "acronym": "SIG", "id": 12178, "rgb_triplet": [209, 97, 70], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12176, 12178]}, {"name": "limbic lobe", "acronym": "LimL", "id": 12155, "rgb_triplet": [209, 206, 226], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12155]}, {"name": "cingulate gyrus", "acronym": "CgG", "id": 12156, "rgb_triplet": [239, 185, 190], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12155, 12156]}, {"name": "cingulate gyrus, rostral (anterior) part", "acronym": "CgGr", "id": 12157, "rgb_triplet": [226, 104, 128], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12155, 12156, 12157]}, {"name": "cingulate gyrus, caudal (posterior) part", "acronym": "CgGc", "id": 12158, "rgb_triplet": [223, 79, 114], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12155, 12156, 12158]}, {"name": "cingulo-parahippocampal isthmus", "acronym": "IsCPH", "id": 12159, "rgb_triplet": [196, 173, 154], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12155, 12159]}, {"name": "subcallosal gyrus (parolfactory gyrus)", "acronym": "SCG", "id": 12160, "rgb_triplet": [226, 104, 128], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12155, 12160]}, {"name": "parahippocampal gyrus", "acronym": "PHG", "id": 12162, "rgb_triplet": [210, 191, 178], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12155, 12162]}, {"name": "anterior parahippocampal gyrus", "acronym": "APH", "id": 12163, "rgb_triplet": [210, 191, 178], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12155, 12162, 12163]}, {"name": "posterior parahippocampal gyrus", "acronym": "PPH", "id": 12164, "rgb_triplet": [193, 81, 132], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12155, 12162, 12164]}, {"name": "uncus of parahippocampal gyrus", "acronym": "UN", "id": 12165, "rgb_triplet": [210, 191, 178], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12155, 12162, 12165]}, {"name": "ambiens gyrus", "acronym": "AG", "id": 12166, "rgb_triplet": [210, 191, 178], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12155, 12162, 12165, 12166]}, {"name": "hippocampal gyrus (formation)", "acronym": "HiF", "id": 12170, "rgb_triplet": [170, 157, 198], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12155, 12170]}, {"name": "head of hippocampus", "acronym": "HiH", "id": 12171, "rgb_triplet": [170, 157, 198], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12155, 12170, 12171]}, {"name": "body of hippocampus", "acronym": "HiB", "id": 12173, "rgb_triplet": [170, 157, 198], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12155, 12170, 12173]}, {"name": "tail of hippocampus", "acronym": "HiT", "id": 12174, "rgb_triplet": [170, 157, 198], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12112, 12155, 12170, 12174]}, {"name": "limen insula", "acronym": "LI", "id": 12179, "rgb_triplet": [208, 208, 209], "structure_id_path": [10153, 10154, 10155, 10156, 10609, 12179]}, {"name": "midbrain (mesencephalon)", "acronym": "M", "id": 10648, "rgb_triplet": [175, 208, 221], "structure_id_path": [10153, 10154, 10155, 10648]}, {"name": "gray matter of midbrain", "acronym": "MGM", "id": 10649, "rgb_triplet": [160, 199, 213], "structure_id_path": [10153, 10154, 10155, 10648, 10649]}, {"name": "pretectal region", "acronym": "PTR", "id": 12181, "rgb_triplet": [160, 199, 213], "structure_id_path": [10153, 10154, 10155, 10648, 10649, 12181]}, {"name": "midbrain tegmentum", "acronym": "MTg", "id": 12195, "rgb_triplet": [82, 152, 174], "structure_id_path": [10153, 10154, 10155, 10648, 10649, 12195]}, {"name": "midbrain tectum", "acronym": "MTc", "id": 12291, "rgb_triplet": [142, 189, 205], "structure_id_path": [10153, 10154, 10155, 10648, 10649, 12291]}, {"name": "superior colliculus", "acronym": "SC", "id": 12292, "rgb_triplet": [126, 179, 201], "structure_id_path": [10153, 10154, 10155, 10648, 10649, 12291, 12292]}, {"name": "inferior colliculus", "acronym": "IC", "id": 12305, "rgb_triplet": [126, 179, 201], "structure_id_path": [10153, 10154, 10155, 10648, 10649, 12291, 12305]}, {"name": "white matter of midbrain", "acronym": "MWM", "id": 10650, "rgb_triplet": [242, 241, 240], "structure_id_path": [10153, 10154, 10155, 10648, 10650]}, {"name": "cerebral peduncle (crus cerebri)", "acronym": "cpd", "id": 12330, "rgb_triplet": [242, 241, 240], "structure_id_path": [10153, 10154, 10155, 10648, 10650, 12330]}, {"name": "superior cerebellar peduncle (brachium conjunctivum)", "acronym": "scp", "id": 12354, "rgb_triplet": [242, 241, 240], "structure_id_path": [10153, 10154, 10155, 10648, 10650, 12354]}, {"name": "ventricle of midbrain", "acronym": "MV", "id": 10651, "rgb_triplet": [35, 31, 32], "structure_id_path": [10153, 10154, 10155, 10648, 10651]}, {"name": "cerebral aqueduct", "acronym": "Aq", "id": 12369, "rgb_triplet": [35, 31, 32], "structure_id_path": [10153, 10154, 10155, 10648, 10651, 12369]}, {"name": "hindbrain (rhombencephalon)", "acronym": "H", "id": 10653, "rgb_triplet": [202, 215, 238], "structure_id_path": [10153, 10154, 10155, 10653]}, {"name": "gray matter of the hindbrain", "acronym": "HGM", "id": 10654, "rgb_triplet": [202, 215, 238], "structure_id_path": [10153, 10154, 10155, 10653, 10654]}, {"name": "metencephalon", "acronym": "Met", "id": 10655, "rgb_triplet": [179, 200, 231], "structure_id_path": [10153, 10154, 10155, 10653, 10654, 10655]}, {"name": "cerebellum", "acronym": "CB", "id": 10656, "rgb_triplet": [158, 186, 225], "structure_id_path": [10153, 10154, 10155, 10653, 10654, 10655, 10656]}, {"name": "cerebellar cortex", "acronym": "CBC", "id": 10657, "rgb_triplet": [137, 173, 219], "structure_id_path": [10153, 10154, 10155, 10653, 10654, 10655, 10656, 10657]}, {"name": "cerebellar vermis", "acronym": "CBV", "id": 10658, "rgb_triplet": [118, 162, 213], "structure_id_path": [10153, 10154, 10155, 10653, 10654, 10655, 10656, 10657, 10658]}, {"name": "cerebellar hemisphere", "acronym": "CBH", "id": 10659, "rgb_triplet": [97, 151, 208], "structure_id_path": [10153, 10154, 10155, 10653, 10654, 10655, 10656, 10657, 10659]}, {"name": "paravermis of cerebellum", "acronym": "CBPV", "id": 12384, "rgb_triplet": [74, 142, 204], "structure_id_path": [10153, 10154, 10155, 10653, 10654, 10655, 10656, 10657, 10659, 12384]}, {"name": "lateral hemisphere of cerebellum", "acronym": "CBL", "id": 12390, "rgb_triplet": [74, 142, 204], "structure_id_path": [10153, 10154, 10155, 10653, 10654, 10655, 10656, 10657, 10659, 12390]}, {"name": "cerebellar deep nuclei", "acronym": "CbDN", "id": 10660, "rgb_triplet": [62, 128, 186], "structure_id_path": [10153, 10154, 10155, 10653, 10654, 10655, 10656, 10660]}, {"name": "pons", "acronym": "Pn", "id": 10661, "rgb_triplet": [175, 195, 219], "structure_id_path": [10153, 10154, 10155, 10653, 10654, 10655, 10661]}, {"name": "basilar part of pons", "acronym": "PnBa", "id": 12405, "rgb_triplet": [120, 147, 199], "structure_id_path": [10153, 10154, 10155, 10653, 10654, 10655, 10661, 12405]}, {"name": "pontine tegmentum", "acronym": "PnTg", "id": 12416, "rgb_triplet": [101, 134, 191], "structure_id_path": [10153, 10154, 10155, 10653, 10654, 10655, 10661, 12416]}, {"name": "myelencephalon (medulla oblongata)", "acronym": "Mo", "id": 10662, "rgb_triplet": [209, 215, 232], "structure_id_path": [10153, 10154, 10155, 10653, 10654, 10662]}, {"name": "pyramidal part of medulla oblongata", "acronym": "MoPy", "id": 12535, "rgb_triplet": [151, 158, 203], "structure_id_path": [10153, 10154, 10155, 10653, 10654, 10662, 12535]}, {"name": "tegmentum of medulla oblongata", "acronym": "MoTg", "id": 12538, "rgb_triplet": [131, 139, 193], "structure_id_path": [10153, 10154, 10155, 10653, 10654, 10662, 12538]}, {"name": "white matter of hindbrain", "acronym": "HWM", "id": 10668, "rgb_triplet": [242, 241, 240], "structure_id_path": [10153, 10154, 10155, 10653, 10668]}, {"name": "ventricles of hindbrain", "acronym": "HV", "id": 10669, "rgb_triplet": [35, 31, 32], "structure_id_path": [10153, 10154, 10155, 10653, 10669]}, {"name": "fourth ventricle", "acronym": "4V", "id": 12805, "rgb_triplet": [35, 31, 32], "structure_id_path": [10153, 10154, 10155, 10653, 10669, 12805]}, {"name": "central canal of medulla oblongata", "acronym": "cec", "id": 12826, "rgb_triplet": [35, 31, 32], "structure_id_path": [10153, 10154, 10155, 10653, 10669, 12826]}]

mindVisualizer/src/field_loader.py

@@ -0,0 +1,192 @@
+"""Load MDN vector fields from metadata JSON + binary grid files."""
+
+import json
+import re
+from pathlib import Path
+from typing import Optional
+
+import numpy as np
+
+
+def load_field(meta_path: Path, grid_bin_path: Optional[Path] = None) -> dict:
+    """
+    Load MDN vector grids and metadata. Supports arbitrary K mixture components.
+    Returns dict with keys: G, amin, amax, mean, mus, pi, ENT, TRAIN, meta.
+    """
+    meta = json.loads(Path(meta_path).read_text(encoding="utf-8"))
+    G = int(meta["grid"])
+    amin = np.array(meta["axis_min"], dtype=np.float32)
+    amax = np.array(meta["axis_max"], dtype=np.float32)
+    files = dict(meta.get("files") or {})
+
+    def _resolve(p):
+        p = Path(p)
+        return p if p.exists() else (Path(meta_path).parent / p)
+
+    def _load_xyz3(fname):
+        raw = np.fromfile(_resolve(fname), dtype=np.float32)
+        return raw.reshape(G, G, G, 3).astype(np.float32)
+
+    def _load_scalar_or_channels(fname):
+        raw = np.fromfile(_resolve(fname), dtype=np.float32)
+        base = G * G * G
+        if raw.size == base:
+            return raw.reshape(G, G, G).astype(np.float32)
+        if raw.size % base == 0:
+            K = raw.size // base
+            return raw.reshape(G, G, G, K).astype(np.float32)
+        raise ValueError(f"{fname}: size {raw.size} incompatible with G^3={base}")
+
+    # mean field
+    if "mean_xyz3" in files:
+        V_mean = _load_xyz3(files["mean_xyz3"])
+    else:
+        if grid_bin_path is None:
+            grid_bin_path = Path(meta_path).with_name(
+                Path(meta_path).name.replace("_meta.json", ".bin"))
+        raw = np.fromfile(grid_bin_path, dtype=np.float32)
+        V_mean = raw.reshape(G, G, G, 3).astype(np.float32)
+
+    # collect mu_k components
+    mu_items = []
+    for k, v in files.items():
+        ks = str(k).lower()
+        if "xyz3" in ks and "mu" in ks:
+            m = re.search(r'(\d+)(?!.*\d)', ks)
+            if m:
+                mu_items.append((int(m.group(1)), v))
+    mu_items.sort(key=lambda kv: kv[0])
+    MUS = [_load_xyz3(fname) for _, fname in mu_items]
+    K_mu = len(MUS)
+
+    # pi (mixture weights)
+    PI = None
+    if "pi" in files:
+        PI = _load_scalar_or_channels(files["pi"])
+        if PI.ndim == 3 and K_mu == 2:
+            PI = np.stack([PI, 1.0 - PI], axis=-1).astype(np.float32)
+
+    # entropy
+    ENT = None
+    if "entropy" in files:
+        ENT = _load_scalar_or_channels(files["entropy"])
+        if ENT.ndim != 3:
+            raise ValueError(f"'entropy' must be (G,G,G); got {ENT.shape}")
+
+    # training points
+    train_pts = None
+    tp_key = meta.get("training_points_npy")
+    if tp_key:
+        p = _resolve(tp_key)
+        if p.exists():
+            train_pts = np.load(p).astype(np.float32)
+
+    return {
+        "G": G, "amin": amin, "amax": amax,
+        "mean": V_mean,
+        "mus": MUS,
+        "pi": PI,
+        "ENT": ENT,
+        "TRAIN": train_pts,
+        "meta": meta,
+    }
+
+
+class TriLinearSampler:
+    """Trilinear interpolation of 3D vector or scalar fields at arbitrary points."""
+
+    def __init__(self, grid_xyz3, amin, amax):
+        self.g = grid_xyz3.astype(np.float32)
+        self.G = grid_xyz3.shape[0]
+        self.amin = amin.astype(np.float32)
+        self.amax = amax.astype(np.float32)
+        span = self.amax - self.amin
+        self.inv_span = np.where(span > 0, 1.0 / span, 0).astype(np.float32)
+
+    def _idx(self, P):
+        f = (P - self.amin) * self.inv_span * (self.G - 1)
+        ix = np.floor(f[:, 0]).astype(np.int32)
+        tx = (f[:, 0] - ix).astype(np.float32)
+        iy = np.floor(f[:, 1]).astype(np.int32)
+        ty = (f[:, 1] - iy).astype(np.float32)
+        iz = np.floor(f[:, 2]).astype(np.int32)
+        tz = (f[:, 2] - iz).astype(np.float32)
+        ix = np.clip(ix, 0, self.G - 2)
+        iy = np.clip(iy, 0, self.G - 2)
+        iz = np.clip(iz, 0, self.G - 2)
+        return ix, iy, iz, tx, ty, tz
+
+    def sample_vec(self, P):
+        ix, iy, iz, tx, ty, tz = self._idx(P)
+        g = self.g
+        v000 = g[ix, iy, iz]
+        v100 = g[ix + 1, iy, iz]
+        v010 = g[ix, iy + 1, iz]
+        v110 = g[ix + 1, iy + 1, iz]
+        v001 = g[ix, iy, iz + 1]
+        v101 = g[ix + 1, iy, iz + 1]
+        v011 = g[ix, iy + 1, iz + 1]
+        v111 = g[ix + 1, iy + 1, iz + 1]
+        vx00 = v000 * (1 - tx)[:, None] + v100 * tx[:, None]
+        vx10 = v010 * (1 - tx)[:, None] + v110 * tx[:, None]
+        vx01 = v001 * (1 - tx)[:, None] + v101 * tx[:, None]
+        vx11 = v011 * (1 - tx)[:, None] + v111 * tx[:, None]
+        vxy0 = vx00 * (1 - ty)[:, None] + vx10 * ty[:, None]
+        vxy1 = vx01 * (1 - ty)[:, None] + vx11 * ty[:, None]
+        out = vxy0 * (1 - tz)[:, None] + vxy1 * tz[:, None]
+        return out.astype(np.float32)
+
+    def sample_scalar(self, S, P):
+        ix, iy, iz, tx, ty, tz = self._idx(P)
+        s000 = S[ix, iy, iz]
+        s100 = S[ix + 1, iy, iz]
+        s010 = S[ix, iy + 1, iz]
+        s110 = S[ix + 1, iy + 1, iz]
+        s001 = S[ix, iy, iz + 1]
+        s101 = S[ix + 1, iy, iz + 1]
+        s011 = S[ix, iy + 1, iz + 1]
+        s111 = S[ix + 1, iy + 1, iz + 1]
+        sx00 = s000 * (1 - tx) + s100 * tx
+        sx10 = s010 * (1 - tx) + s110 * tx
+        sx01 = s001 * (1 - tx) + s101 * tx
+        sx11 = s011 * (1 - tx) + s111 * tx
+        return (sx00 * (1 - ty) + sx10 * ty) * (1 - tz) + (sx01 * (1 - ty) + sx11 * ty) * tz
+
+
+def load_points_any(path: Path) -> np.ndarray:
+    """Load point cloud from .npy, .obj, or .ply file."""
+    p = Path(path)
+    if p.suffix.lower() == ".npy":
+        return np.asarray(np.load(p), np.float32)
+    if p.suffix.lower() == ".obj":
+        pts = []
+        with open(p, "r", encoding="utf-8", errors="ignore") as f:
+            for line in f:
+                if not line or line[0] != 'v' or (len(line) > 1 and line[1] not in (' ', '\t')):
+                    continue
+                parts = line.strip().split()
+                if len(parts) >= 4:
+                    pts.append([float(parts[1]), float(parts[2]), float(parts[3])])
+        return np.asarray(pts, np.float32)
+    if p.suffix.lower() == ".ply":
+        with open(p, "r", encoding="utf-8", errors="ignore") as f:
+            header = []
+            while True:
+                line = f.readline()
+                if not line:
+                    raise ValueError("Invalid PLY (no end_header)")
+                header.append(line.strip())
+                if line.strip() == "end_header":
+                    break
+            nverts = 0
+            for h in header:
+                if h.startswith("element vertex"):
+                    nverts = int(h.split()[-1])
+                    break
+            pts = []
+            for _ in range(nverts):
+                parts = f.readline().strip().split()
+                if len(parts) >= 3:
+                    pts.append([float(parts[0]), float(parts[1]), float(parts[2])])
+        return np.asarray(pts, np.float32)
+    raise ValueError(f"Unsupported point format: {p.suffix}")

mindVisualizer/src/region_analyzer.py

@@ -0,0 +1,703 @@
+"""Analyze probe trajectory through brain regions and explain transitions via GPT."""
+
+import json
+import os
+from pathlib import Path
+
+import numpy as np
+
+# Path to RAG knowledge files (JSON and TXT files with brain region descriptions)
+RAG_KNOWLEDGE_DIR = Path(__file__).resolve().parent.parent / "data" / "rag_knowledge"
+
+
+
+def load_knowledge_from_files(directory: Path | None = None) -> dict[str, str]:
+    """Load brain region knowledge from user-supplied JSON and TXT files.
+
+    JSON files: {"Region Name": "description", ...}
+    TXT files: sections separated by '## Region Name' headers.
+
+    Returns merged dict. Empty dict if directory missing/empty.
+    """
+    directory = directory or RAG_KNOWLEDGE_DIR
+    knowledge: dict[str, str] = {}
+    if not directory.is_dir():
+        return knowledge
+
+    # Process files in sorted order for deterministic merging
+    for fpath in sorted(directory.iterdir()):
+        if fpath.suffix == ".json":
+            try:
+                data = json.loads(fpath.read_text(encoding="utf-8"))
+                if isinstance(data, dict):
+                    count = 0
+                    for k, v in data.items():
+                        if isinstance(k, str) and isinstance(v, str):
+                            knowledge[k] = v
+                            count += 1
+                    if count:
+                        print(f"[RAG] Loaded {count} regions from {fpath.name}")
+            except Exception as e:
+                print(f"[RAG] Warning: could not load {fpath.name}: {e}")
+
+        elif fpath.suffix == ".txt":
+            try:
+                text = fpath.read_text(encoding="utf-8")
+                current_region = None
+                current_lines: list[str] = []
+                count = 0
+                for line in text.splitlines():
+                    if line.startswith("## "):
+                        if current_region and current_lines:
+                            knowledge[current_region] = " ".join(current_lines).strip()
+                            count += 1
+                        current_region = line[3:].strip()
+                        current_lines = []
+                    elif current_region is not None:
+                        current_lines.append(line.strip())
+                if current_region and current_lines:
+                    knowledge[current_region] = " ".join(current_lines).strip()
+                    count += 1
+                if count:
+                    print(f"[RAG] Loaded {count} regions from {fpath.name}")
+            except Exception as e:
+                print(f"[RAG] Warning: could not load {fpath.name}: {e}")
+
+    return knowledge
+
+
+def _call_direct_responses_api(question: str, model: str) -> str:
+    """Direct OpenAI Responses API call for no-RAG mode.
+
+    Avoids the LangChain empty-content failure path seen with GPT-5.4 in the
+    background thread.
+    """
+    _ensure_ssl()
+
+    from dotenv import load_dotenv
+    load_dotenv()
+
+    from openai import OpenAI
+
+    client = OpenAI(timeout=60.0)
+
+    instructions = (
+        "You are a neuroscience expert interpreting information flow in a "
+        "resting-state brain.\n\n"
+        "Do NOT repeat the region list.\n"
+        "Do explain:\n"
+        "1. what specific information is likely flowing,\n"
+        "2. how the signal is transformed across regions,\n"
+        "3. what spontaneous resting-state process could produce this path,\n"
+        "4. the functional purpose of this exact trajectory.\n"
+        "Be concrete, not generic."
+    )
+
+    resp = client.responses.create(
+        model=model,
+        instructions=instructions,
+        input=question,
+        # This is not a model downgrade. It just keeps enough budget for the visible answer.
+        reasoning={"effort": "low"},
+        max_output_tokens=2500,
+        # Optional, if your SDK/version accepts it and you want longer answers:
+        # text={"verbosity": "high"},
+    )
+
+    text = (resp.output_text or "").strip()
+    if text:
+        return text
+
+    if getattr(resp, "status", None) == "incomplete" and getattr(resp, "incomplete_details", None):
+        reason = getattr(resp.incomplete_details, "reason", "unknown")
+        return f"[GPT ERROR] Responses API incomplete: {reason}"
+
+    return "[GPT ERROR] Responses API returned no visible text."
+
+def _get_mesh_volume(mesh_overlay, key: str) -> float:
+    """Estimate mesh volume from bounding box (for nesting detection)."""
+    bounds = mesh_overlay.get_mesh_bounds(key)
+    if bounds is None:
+        return float('inf')
+    return float((bounds[1] - bounds[0]) * (bounds[3] - bounds[2]) * (bounds[5] - bounds[4]))
+
+
+def analyze_probe_path(path_positions: np.ndarray, mesh_overlay,
+                       sample_every: int = 10,
+                       field_mags: np.ndarray | None = None,
+                       entropy_sampler=None,
+                       entropy_field=None) -> list[dict]:
+    """Analyze which brain regions the probe traveled through.
+
+    Handles nested regions: when the probe is inside multiple overlapping
+    regions (e.g., a subregion inside a larger area), the smaller region
+    is treated as the primary region and the larger one as context.
+
+    Args:
+        path_positions: (N,3) probe path
+        mesh_overlay: FlowMeshOverlay instance
+        sample_every: check every N steps
+        field_mags: raw field magnitudes (independent of speed scale)
+        entropy_sampler: TriLinearSampler for entropy
+        entropy_field: entropy grid (G,G,G) numpy array
+
+    Returns a list of dicts with keys: region_key, region_name, entry_idx,
+    exit_idx, relative_position, avg_flow_strength, avg_entropy,
+    enclosing_regions.
+    """
+    if len(path_positions) == 0:
+        return []
+
+    region_keys = mesh_overlay.get_all_region_keys()
+    # Pre-compute volumes for nesting detection
+    volumes = {k: _get_mesh_volume(mesh_overlay, k) for k in region_keys}
+
+    transitions = []
+    prev_regions = set()
+
+    for i in range(0, len(path_positions), sample_every):
+        pt = path_positions[i]
+        in_regions = set()
+
+        for key in region_keys:
+            if mesh_overlay.point_in_mesh(pt, key):
+                in_regions.add(key)
+
+        # Sample entropy at this point
+        ent_val = None
+        if entropy_sampler is not None and entropy_field is not None:
+            try:
+                ent_val = float(entropy_sampler.sample_scalar(entropy_field, pt[None, :])[0])
+            except Exception:
+                pass
+
+        # Detect entries
+        entered = in_regions - prev_regions
+        for key in entered:
+            center = mesh_overlay.get_mesh_center(key)
+            rel_pos = _relative_position(pt, center, mesh_overlay.get_mesh_bounds(key))
+
+            # Find enclosing (larger) regions at this point
+            enclosing = []
+            for other_key in in_regions:
+                if other_key != key and volumes.get(other_key, 0) > volumes.get(key, 0):
+                    enclosing.append(mesh_overlay.get_region_name(other_key))
+
+            # Flow strength (independent of speed scale)
+            flow_str = None
+            if field_mags is not None and i < len(field_mags):
+                flow_str = float(field_mags[i])
+
+            # Hemisphere info (if mesh_overlay supports it)
+            hemisphere = None
+            if hasattr(mesh_overlay, 'get_hemisphere_label'):
+                try:
+                    hemisphere = mesh_overlay.get_hemisphere_label(key, pt)
+                except Exception:
+                    pass
+
+            transition_dict = {
+                "region_key": key,
+                "region_name": mesh_overlay.get_region_name(key),
+                "entry_idx": i,
+                "exit_idx": None,
+                "relative_position": rel_pos,
+                "entry_point": pt.copy(),
+                "enclosing_regions": enclosing,
+                "avg_flow_strength": flow_str,
+                "avg_entropy": ent_val,
+                "_flow_samples": [flow_str] if flow_str is not None else [],
+                "_ent_samples": [ent_val] if ent_val is not None else [],
+            }
+            if hemisphere is not None:
+                transition_dict["hemisphere"] = hemisphere
+
+            # Extra parcellation subregion info
+            if hasattr(mesh_overlay, '_extra') and mesh_overlay._extra is not None:
+                sub = mesh_overlay._extra.get_region_at_point(pt)
+                if sub is not None:
+                    transition_dict["subregion_name"] = sub["name"]
+                    transition_dict["subregion_volume"] = sub["volume_mm3"]
+
+            transitions.append(transition_dict)
+
+        # Accumulate samples for active transitions
+        for t in transitions:
+            if t["exit_idx"] is None:
+                if field_mags is not None and i < len(field_mags):
+                    t["_flow_samples"].append(float(field_mags[i]))
+                if ent_val is not None:
+                    t["_ent_samples"].append(ent_val)
+
+        # Detect exits
+        exited = prev_regions - in_regions
+        for key in exited:
+            for t in reversed(transitions):
+                if t["region_key"] == key and t["exit_idx"] is None:
+                    t["exit_idx"] = i
+                    if t["_flow_samples"]:
+                        t["avg_flow_strength"] = float(np.mean(t["_flow_samples"]))
+                    if t["_ent_samples"]:
+                        t["avg_entropy"] = float(np.mean(t["_ent_samples"]))
+                    break
+
+        prev_regions = in_regions
+
+    # Close any still-open regions
+    for t in transitions:
+        if t["exit_idx"] is None:
+            t["exit_idx"] = len(path_positions) - 1
+            if t["_flow_samples"]:
+                t["avg_flow_strength"] = float(np.mean(t["_flow_samples"]))
+            if t["_ent_samples"]:
+                t["avg_entropy"] = float(np.mean(t["_ent_samples"]))
+
+    # Pre-compute sampled path points for nearby detection / enrichment
+    sampled_pts = path_positions[::sample_every]
+
+    # --- Enrich each transition with detailed interaction context ---
+    for t in transitions:
+        key = t["region_key"]
+        entry_i = t["entry_idx"]
+        exit_i = t["exit_idx"] if t["exit_idx"] is not None else len(path_positions) - 1
+
+        center = mesh_overlay.get_mesh_center(key)
+        bounds = mesh_overlay.get_mesh_bounds(key)
+
+        # Collect all path points inside this region's span
+        inside_pts = path_positions[entry_i:exit_i + 1:sample_every]
+
+        # 1. Interaction type: how deeply the probe penetrated
+        if center is not None and bounds is not None and len(inside_pts) > 0:
+            extent = np.array([bounds[1]-bounds[0], bounds[3]-bounds[2],
+                               bounds[5]-bounds[4]])
+            extent = np.maximum(extent, 1e-6)
+            char_size = float(np.mean(extent))  # characteristic region size
+
+            # Distance from each inside point to region center
+            dists_to_center = np.linalg.norm(inside_pts - center, axis=1)
+            min_dist = float(dists_to_center.min())
+            mean_dist = float(dists_to_center.mean())
+            # Normalized penetration depth (0 = at center, 1 = at edge)
+            penetration = 1.0 - min(min_dist / (char_size * 0.5), 1.0)
+
+            if penetration > 0.6:
+                interaction = "passed through center"
+            elif penetration > 0.3:
+                interaction = "traversed mid-region"
+            elif len(inside_pts) <= 2:
+                interaction = "briefly touched surface"
+            else:
+                interaction = "passed through periphery"
+            t["interaction_type"] = interaction
+            t["penetration_depth"] = round(penetration, 2)
+        else:
+            t["interaction_type"] = "traversed"
+            t["penetration_depth"] = None
+
+        # 2. Exit position (relative to region)
+        if exit_i < len(path_positions) and center is not None and bounds is not None:
+            exit_pt = path_positions[min(exit_i, len(path_positions) - 1)]
+            t["exit_position"] = _relative_position(exit_pt, center, bounds)
+        else:
+            t["exit_position"] = "unknown"
+
+        # 3. Traversal direction through the region
+        if len(inside_pts) >= 2:
+            direction_vec = inside_pts[-1] - inside_pts[0]
+            norm = np.linalg.norm(direction_vec)
+            if norm > 1e-6:
+                d = direction_vec / norm
+                dir_parts = []
+                if abs(d[2]) > 0.3:
+                    dir_parts.append("upward" if d[2] > 0 else "downward")
+                if abs(d[0]) > 0.3:
+                    dir_parts.append("rightward" if d[0] > 0 else "leftward")
+                if abs(d[1]) > 0.3:
+                    dir_parts.append("anteriorly" if d[1] > 0 else "posteriorly")
+                t["traversal_direction"] = " and ".join(dir_parts) if dir_parts else "through"
+            else:
+                t["traversal_direction"] = "stationary"
+        else:
+            t["traversal_direction"] = "brief"
+
+    # --- Detect nearby regions (probe flowed close but never entered) ---
+    entered_keys = {t["region_key"] for t in transitions}
+    NEARBY_THRESHOLD_MM = 5.0  # max distance to consider "nearby"
+    nearby_transitions = []
+
+    for key in region_keys:
+        if key in entered_keys:
+            continue
+        center = mesh_overlay.get_mesh_center(key)
+        bounds = mesh_overlay.get_mesh_bounds(key)
+        if center is None or bounds is None:
+            continue
+        extent = np.array([bounds[1]-bounds[0], bounds[3]-bounds[2],
+                           bounds[5]-bounds[4]])
+        extent = np.maximum(extent, 1e-6)
+        char_size = float(np.mean(extent))
+
+        # Check minimum distance from any sampled path point to region center
+        dists = np.linalg.norm(sampled_pts - center, axis=1)
+        min_dist = float(dists.min())
+        # "nearby" = within threshold but also within the region's own characteristic size
+        effective_radius = max(char_size * 0.5, NEARBY_THRESHOLD_MM)
+        if min_dist < effective_radius:
+            closest_idx = int(dists.argmin()) * sample_every
+            name = mesh_overlay.get_region_name(key)
+            hemisphere = None
+            if hasattr(mesh_overlay, 'get_hemisphere_label'):
+                try:
+                    hemisphere = mesh_overlay.get_hemisphere_label(
+                        key, sampled_pts[int(dists.argmin())])
+                except Exception:
+                    pass
+            nearby_t = {
+                "region_key": key,
+                "region_name": name,
+                "entry_idx": closest_idx,
+                "exit_idx": closest_idx,
+                "relative_position": _relative_position(
+                    sampled_pts[int(dists.argmin())], center, bounds),
+                "entry_point": sampled_pts[int(dists.argmin())].copy(),
+                "enclosing_regions": [],
+                "avg_flow_strength": None,
+                "avg_entropy": None,
+                "interaction_type": f"nearby (did not enter, ~{min_dist:.1f}mm away)",
+                "penetration_depth": 0.0,
+                "exit_position": "n/a",
+                "traversal_direction": "n/a",
+            }
+            if hemisphere is not None:
+                nearby_t["hemisphere"] = hemisphere
+            nearby_transitions.append(nearby_t)
+
+    transitions.extend(nearby_transitions)
+
+    # Clean up internal fields
+    for t in transitions:
+        t.pop("_flow_samples", None)
+        t.pop("_ent_samples", None)
+
+    # Sort by volume (smaller = more specific) so primary regions come first at each transition
+    transitions.sort(key=lambda t: (t["entry_idx"], volumes.get(t["region_key"], float('inf'))))
+
+    return transitions
+
+
+def _relative_position(point: np.ndarray, center: np.ndarray | None,
+                       bounds: np.ndarray | None) -> str:
+    """Describe position relative to region center (e.g., 'upper-left')."""
+    if center is None or bounds is None:
+        return "unknown"
+
+    diff = point - center
+    extent = np.array([
+        bounds[1] - bounds[0],
+        bounds[3] - bounds[2],
+        bounds[5] - bounds[4],
+    ])
+    extent = np.maximum(extent, 1e-6)
+    rel = diff / (extent * 0.5)  # normalized to [-1, 1]
+
+    parts = []
+    if abs(rel[2]) > 0.3:
+        parts.append("upper" if rel[2] > 0 else "lower")
+    if abs(rel[0]) > 0.3:
+        parts.append("right" if rel[0] > 0 else "left")
+    if abs(rel[1]) > 0.3:
+        parts.append("anterior" if rel[1] > 0 else "posterior")
+
+    if not parts:
+        return "center"
+    return "-".join(parts)
+
+
+def format_transitions_text(transitions: list[dict],
+                            include_branches: list[dict] | None = None) -> str:
+    """Format transitions into a human-readable description for GPT.
+
+    Handles nested regions: smaller (more specific) regions are primary,
+    with larger enclosing regions noted as context.
+    """
+    if not transitions:
+        return "The probe did not pass through any identified brain regions."
+
+    lines = ["The probe traveled through the following brain regions in order:\n"]
+    for i, t in enumerate(transitions, 1):
+        duration = (t["exit_idx"] or 0) - (t["entry_idx"] or 0)
+
+        # Include hemisphere in region name if available
+        region_label = t['region_name']
+        hemisphere = t.get("hemisphere")
+        if hemisphere:
+            region_label = f"{region_label} ({hemisphere})"
+
+        extras = []
+        if t.get("avg_flow_strength") is not None:
+            extras.append(f"flow_strength={t['avg_flow_strength']:.4f}")
+        if t.get("avg_entropy") is not None:
+            extras.append(f"model_entropy={t['avg_entropy']:.3f} "
+                          f"({'high uncertainty' if t['avg_entropy'] > 1.5 else 'confident'})")
+        extras_str = f", {', '.join(extras)}" if extras else ""
+
+        enclosing = t.get("enclosing_regions", [])
+        ctx_str = ""
+        if enclosing:
+            ctx_str = f" [within larger region: {', '.join(enclosing)}]"
+
+        # Extra parcellation subregion info
+        subregion = t.get("subregion_name")
+        sub_str = ""
+        if subregion:
+            sub_str = f", more specifically in subregion: {subregion}"
+
+        # Interaction detail from enrichment
+        interaction = t.get("interaction_type", "traversed")
+        is_nearby = "nearby" in interaction
+
+        if is_nearby:
+            # Nearby region: compact format, no penetration/direction/exit noise
+            entry_pos = t.get("relative_position", "unknown")
+            pos_str = f" near {entry_pos} section" if entry_pos and entry_pos != "unknown" else ""
+            lines.append(
+                f"{i}. {region_label} — {interaction}{pos_str}{ctx_str}{sub_str}"
+            )
+        else:
+            penetration = t.get("penetration_depth")
+            direction = t.get("traversal_direction", "")
+            exit_pos = t.get("exit_position", "")
+
+            # Build detailed description
+            detail_parts = [f"{interaction}"]
+            if penetration is not None:
+                detail_parts.append(f"penetration depth {penetration:.0%}")
+            if direction and direction not in ("brief", "stationary", "through", "n/a"):
+                detail_parts.append(f"moving {direction}")
+            detail_str = ", ".join(detail_parts)
+
+            entry_pos = t.get("relative_position", "unknown")
+            exit_str = f", exited from {exit_pos}" if exit_pos and exit_pos not in ("unknown", "n/a") else ""
+
+            lines.append(
+                f"{i}. {region_label} — {detail_str}. "
+                f"Entered at {entry_pos}{exit_str}, "
+                f"~{duration} steps inside{extras_str}{ctx_str}{sub_str}"
+            )
+
+    if include_branches:
+        lines.append("\nBranching events (alternative flow paths detected):")
+        for b in include_branches:
+            lines.append(f"  - Branch at step ~{b.get('entry_idx', '?')}: "
+                         f"flow split toward {b.get('region_name', 'unknown')}")
+
+    return "\n".join(lines)
+
+
+def build_rag_documents():
+    """Build LangChain documents from the RAG knowledge base.
+
+    Loads all JSON and TXT files from data/rag_knowledge/.
+    If no files are found, the RAG chain will have no context and the
+    LLM will rely on its own training knowledge.
+    """
+    from langchain_core.documents import Document
+
+    knowledge = load_knowledge_from_files()
+    if not knowledge:
+        print("[RAG] Warning: no knowledge files found in data/rag_knowledge/. "
+              "LLM will use its own training knowledge only.")
+
+    docs = []
+    for name, desc in knowledge.items():
+        docs.append(Document(
+            page_content=f"Brain Region: {name}\nFunction: {desc}",
+            metadata={"region_name": name}
+        ))
+    return docs
+
+
+def _ensure_ssl():
+    """Fix SSL cert path for environments where Git overrides it."""
+    try:
+        import certifi
+        cert_file = certifi.where()
+        # Force override if current path is missing (Git installer on Windows
+        # often sets SSL_CERT_FILE to a non-existent path)
+        cur = os.environ.get("SSL_CERT_FILE", "")
+        if not cur or not os.path.isfile(cur):
+            os.environ["SSL_CERT_FILE"] = cert_file
+        cur2 = os.environ.get("REQUESTS_CA_BUNDLE", "")
+        if not cur2 or not os.path.isfile(cur2):
+            os.environ["REQUESTS_CA_BUNDLE"] = cert_file
+    except ImportError:
+        pass
+
+
+def create_rag_chain(model: str = "gpt-5.4-mini"):
+    """Create a LangChain RAG chain with region knowledge."""
+    _ensure_ssl()
+
+    from dotenv import load_dotenv
+    load_dotenv()
+
+    from langchain_openai import ChatOpenAI, OpenAIEmbeddings
+    from langchain_community.vectorstores import FAISS
+    from langchain_core.prompts import ChatPromptTemplate
+    from langchain_core.runnables import RunnablePassthrough
+    from langchain_core.output_parsers import StrOutputParser
+
+    docs = build_rag_documents()
+
+    embeddings = OpenAIEmbeddings(model="text-embedding-3-small")
+    vectorstore = FAISS.from_documents(docs, embeddings)
+    retriever = vectorstore.as_retriever(search_kwargs={"k": 10})
+
+    prompt = ChatPromptTemplate.from_template(
+        """You are a neuroscience expert interpreting information flow in a resting-state brain.
+
+Reference knowledge about relevant brain regions:
+{context}
+
+{question}
+
+CRITICAL INSTRUCTIONS — read carefully before answering:
+1. Do NOT list which regions the probe passed through — the user already knows that.
+2. Do NOT give a generic answer like "this flow is associated with the default mode network" — that is too shallow.
+3. DO explain what SPECIFIC INFORMATION is likely flowing along this exact path. What is being computed, processed, or communicated? How does the information CHANGE as it passes through each region?
+4. DO describe the functional MEANING of this particular flow trajectory: why would information flow in this exact direction, through these specific regions, in this order? What is the computational purpose?
+5. DO explain how each region transforms the signal before passing it on — not just what each region "does" in general, but what it does to THIS specific incoming signal.
+6. DO consider laterality: if the flow is in the left or right hemisphere, explain what that implies about the type of processing (e.g., left-lateralized language processing, right-lateralized spatial processing).
+7. This is a RESTING-STATE brain — describe what spontaneous cognitive process would produce this exact flow. Be concrete: "the brain is likely consolidating a recent spatial memory" is better than "this involves memory processing."
+
+Note: the flow direction reflects rDCM effective connectivity (who influences whom), not neural signal timing. Particle speed is a visualization scale, not biological latency.
+"""
+    )
+
+    llm = ChatOpenAI(model=model, temperature=0.3, max_tokens=1500)
+
+    def format_docs(docs):
+        return "\n\n".join(doc.page_content for doc in docs)
+
+    chain = (
+        {"context": retriever | format_docs, "question": RunnablePassthrough()}
+        | prompt
+        | llm
+        | StrOutputParser()
+    )
+
+    return chain
+
+
+def create_direct_chain(model: str = "gpt-5.4-mini"):
+    """Create a direct GPT chain without RAG (uses only GPT's own knowledge)."""
+    _ensure_ssl()
+
+    from dotenv import load_dotenv
+    load_dotenv()
+
+    from langchain_openai import ChatOpenAI
+    from langchain_core.prompts import ChatPromptTemplate
+    from langchain_core.runnables import RunnablePassthrough
+    from langchain_core.output_parsers import StrOutputParser
+
+    prompt = ChatPromptTemplate.from_template(
+        """You are a neuroscience expert interpreting information flow in a resting-state brain.
+
+Using your deep knowledge of neuroanatomy, functional connectivity, and resting-state \
+networks, answer the following question:
+
+{question}
+
+CRITICAL INSTRUCTIONS — read carefully before answering:
+1. Do NOT list which regions the probe passed through — the user already knows that.
+2. Do NOT give a generic answer like "this flow is associated with the default mode network" — that is too shallow.
+3. DO explain what SPECIFIC INFORMATION is likely flowing along this exact path. What is being computed, processed, or communicated? How does the information CHANGE as it passes through each region?
+4. DO describe the functional MEANING of this particular flow trajectory: why would information flow in this exact direction, through these specific regions, in this order? What is the computational purpose?
+5. DO explain how each region transforms the signal before passing it on — not just what each region "does" in general, but what it does to THIS specific incoming signal.
+6. DO consider laterality: if the flow is in the left or right hemisphere, explain what that implies about the type of processing (e.g., left-lateralized language processing, right-lateralized spatial processing).
+7. This is a RESTING-STATE brain — describe what spontaneous cognitive process would produce this exact flow. Be concrete: "the brain is likely consolidating a recent spatial memory" is better than "this involves memory processing."
+
+Note: the flow direction reflects rDCM effective connectivity (who influences whom), not neural signal timing. Particle speed is a visualization scale, not biological latency.
+"""
+    )
+
+    llm = ChatOpenAI(model=model, temperature=0.3, max_tokens=1500)
+
+    chain = (
+        {"question": RunnablePassthrough()}
+        | prompt
+        | llm
+        | StrOutputParser()
+    )
+
+    return chain
+
+
+_rag_chain = None
+_direct_chain = None
+_cached_model = None
+
+
+def analyze_with_gpt(transitions: list[dict], use_rag: bool = True,
+                     model: str = "gpt-5.4-mini",
+                     debug: bool = False) -> str:
+    global _rag_chain, _direct_chain, _cached_model
+
+    if not transitions:
+        return "No brain regions were traversed. Place the probe inside the brain volume."
+
+    description = format_transitions_text(transitions)
+    question = (
+        f"A probe was placed in a resting-state brain and followed the intrinsic information "
+        f"flow field through these regions:\n\n{description}\n\n"
+        f"Analyze this SPECIFIC flow pathway in depth:\n"
+        f"1. What concrete information is likely being carried along this path?\n"
+        f"2. How does the information CHANGE and get TRANSFORMED as it passes through each region?\n"
+        f"3. What spontaneous resting-state cognitive process would produce this EXACT flow?\n"
+        f"4. What is the functional PURPOSE of information flowing in this exact direction and order?\n"
+        f"Do NOT repeat the region list or give a generic network label. Give deep, specific insight.\n"
+        f"Keep your response SHORT and focused — 2-3 concise paragraphs maximum."
+    )
+
+    if debug:
+        import sys
+        print(f"\n{'='*60}")
+        print(f"[DEBUG PROMPT] analyze_with_gpt (use_rag={use_rag}, model={model})")
+        print(f"{'='*60}")
+        print(question)
+        print(f"{'='*60}\n")
+        sys.stdout.flush()
+
+    # IMPORTANT: bypass LangChain entirely for no-RAG mode
+    if not use_rag:
+        try:
+            print(f"[GPT] Using Responses API directly (model={model}, no RAG)...")
+            return _call_direct_responses_api(question, model)
+        except Exception as e:
+            import traceback
+            traceback.print_exc()
+            return f"[GPT ERROR] Direct Responses API failed: {e}"
+
+    # keep existing RAG path for now
+    if _cached_model != model:
+        _rag_chain = None
+        _direct_chain = None
+        _cached_model = model
+
+    if _rag_chain is None:
+        print(f"[GPT] Initializing RAG chain (model={model})...")
+        try:
+            _rag_chain = create_rag_chain(model=model)
+        except Exception as e:
+            return f"[GPT ERROR] Failed to initialize RAG: {e}"
+
+    try:
+        result = _rag_chain.invoke(question)
+        text = result if isinstance(result, str) else str(result)
+        return text.strip() if text and text.strip() else "[GPT ERROR] Empty RAG response."
+    except Exception as e:
+        import traceback
+        traceback.print_exc()
+        return f"[GPT ERROR] {e}"

mindVisualizer/src/roi_flow.py

@@ -0,0 +1,403 @@
+"""ROI Flow mode: manifold-to-ROI mapping and LLM interpretation.
+
+Maps probe positions in a learned neural manifold to ROI activation vectors
+using k-nearest-neighbor interpolation, then analyzes how the ROI pattern
+changes along the probe path.
+
+This module is used by examples/roi_flow_mode.py for the dual-window
+manifold + ROI visualization.
+"""
+
+import os
+from pathlib import Path
+
+import numpy as np
+from scipy.spatial import cKDTree
+
+
+# ---------------------------------------------------------------------------
+# Manifold-to-ROI mapper
+# ---------------------------------------------------------------------------
+
+class ManifoldToROIKNN:
+    """Map manifold positions to ROI activation vectors via kNN + Gaussian weighting.
+
+    Given a library of (embedding_point, roi_vector) pairs, interpolates
+    the ROI vector at any manifold position using Gaussian-weighted kNN.
+    """
+
+    def __init__(self, embed_points: np.ndarray, roi_vectors: np.ndarray,
+                 k: int = 256, sigma: float = 0.0):
+        """
+        Args:
+            embed_points: (N, D) embedding coordinates (typically D=3).
+            roi_vectors: (N, R) ROI activation vectors.
+            k: number of nearest neighbors for interpolation.
+            sigma: Gaussian bandwidth. If 0, auto-computed from median kNN distance.
+        """
+        assert embed_points.shape[0] == roi_vectors.shape[0], \
+            f"embed ({embed_points.shape[0]}) and roi ({roi_vectors.shape[0]}) must match"
+        self.X = embed_points.astype(np.float32)
+        self.Y = roi_vectors.astype(np.float32)
+        self.k = int(max(8, k))
+        self.sigma = float(max(0.0, sigma))
+        self.n_rois = self.Y.shape[1]
+        self.tree = cKDTree(self.X)
+
+    def query(self, point: np.ndarray) -> np.ndarray:
+        """Interpolate ROI vector at a manifold position.
+
+        Args:
+            point: (D,) or (1,D) position in manifold space.
+
+        Returns:
+            (R,) ROI activation vector.
+        """
+        p = point.reshape(1, -1).astype(np.float32)
+        k_actual = min(self.k, len(self.X))
+        d, idx = self.tree.query(p, k=k_actual)
+        d = np.asarray(d).ravel().astype(np.float32)
+        idx = np.asarray(idx).ravel()
+
+        if len(idx) == 0:
+            return np.zeros(self.n_rois, dtype=np.float32)
+
+        sig = self.sigma if self.sigma > 0 else float(np.median(d) + 1e-9)
+        w = np.exp(-(d ** 2) / (2.0 * sig ** 2)).astype(np.float64)
+        sw = float(np.sum(w)) + 1e-12
+        mu = (w[:, None] * self.Y[idx]).sum(axis=0) / sw
+        return mu.astype(np.float32)
+
+
+# ---------------------------------------------------------------------------
+# ROI flow analyzer
+# ---------------------------------------------------------------------------
+
+class ROIFlowAnalyzer:
+    """Analyze ROI delta vectors to extract flow patterns for LLM interpretation."""
+
+    def __init__(self, roi_names: list[str], roi_centers: np.ndarray):
+        """
+        Args:
+            roi_names: (R,) human-readable ROI names.
+            roi_centers: (R, 3) MNI coordinates of ROI centers.
+        """
+        self.roi_names = roi_names
+        self.roi_centers = roi_centers.astype(np.float32)
+        self.n_rois = len(roi_names)
+
+    def compute_delta(self, start_roi: np.ndarray, end_roi: np.ndarray) -> np.ndarray:
+        """Compute change in ROI activation from start to end of path."""
+        return (end_roi - start_roi).astype(np.float32)
+
+    def analyze_flow_pattern(self, delta: np.ndarray) -> dict:
+        """Extract structured information about the ROI flow pattern.
+
+        Returns dict with:
+            top_positive: list of (name, delta_val, center) for top increased ROIs
+            top_negative: list of (name, delta_val, center) for top decreased ROIs
+            direction: dict with anterior_posterior, left_right, superior_inferior scores
+            pattern_type: "one_to_many", "many_to_one", "distributed", "bilateral_split"
+            bulk_direction: human-readable description of dominant flow direction
+        """
+        abs_delta = np.abs(delta)
+        threshold = np.percentile(abs_delta, 85)
+
+        # Top changed ROIs
+        significant = abs_delta > threshold
+        pos_mask = (delta > 0) & significant
+        neg_mask = (delta < 0) & significant
+
+        pos_indices = np.where(pos_mask)[0]
+        neg_indices = np.where(neg_mask)[0]
+
+        # Sort by magnitude
+        pos_sorted = pos_indices[np.argsort(-delta[pos_indices])]
+        neg_sorted = neg_indices[np.argsort(delta[neg_indices])]
+
+        top_positive = [(self.roi_names[i], float(delta[i]),
+                         self.roi_centers[i].tolist()) for i in pos_sorted[:10]]
+        top_negative = [(self.roi_names[i], float(delta[i]),
+                         self.roi_centers[i].tolist()) for i in neg_sorted[:10]]
+
+        # Compute directional bias using weighted centroids
+        pos_weighted_center = np.zeros(3)
+        neg_weighted_center = np.zeros(3)
+        if len(pos_indices) > 0:
+            w = delta[pos_indices]
+            pos_weighted_center = np.average(self.roi_centers[pos_indices], axis=0,
+                                             weights=w)
+        if len(neg_indices) > 0:
+            w = np.abs(delta[neg_indices])
+            neg_weighted_center = np.average(self.roi_centers[neg_indices], axis=0,
+                                             weights=w)
+
+        # Direction: from negative (source) to positive (target) centroids
+        flow_vec = pos_weighted_center - neg_weighted_center
+        direction = {
+            "left_right": float(flow_vec[0]),      # +X = right
+            "anterior_posterior": float(flow_vec[1]),  # +Y = anterior
+            "superior_inferior": float(flow_vec[2]),   # +Z = superior
+        }
+
+        # Pattern type
+        n_pos = len(pos_indices)
+        n_neg = len(neg_indices)
+        if n_neg <= 3 and n_pos > 8:
+            pattern_type = "one_to_many"
+        elif n_pos <= 3 and n_neg > 8:
+            pattern_type = "many_to_one"
+        elif n_pos > 0 and n_neg > 0:
+            # Check bilateral split
+            pos_x = self.roi_centers[pos_indices, 0]
+            neg_x = self.roi_centers[neg_indices, 0]
+            pos_mean_x = float(np.mean(pos_x))
+            neg_mean_x = float(np.mean(neg_x))
+            if abs(pos_mean_x - neg_mean_x) > 20:  # significant L/R separation
+                pattern_type = "bilateral_split"
+            else:
+                pattern_type = "distributed"
+        else:
+            pattern_type = "distributed"
+
+        # Human-readable bulk direction
+        parts = []
+        if abs(direction["anterior_posterior"]) > 10:
+            parts.append("anterior" if direction["anterior_posterior"] > 0 else "posterior")
+        if abs(direction["left_right"]) > 10:
+            parts.append("right" if direction["left_right"] > 0 else "left")
+        if abs(direction["superior_inferior"]) > 10:
+            parts.append("superior" if direction["superior_inferior"] > 0 else "inferior")
+        bulk_direction = " and ".join(parts) if parts else "no dominant direction"
+
+        return {
+            "top_positive": top_positive,
+            "top_negative": top_negative,
+            "direction": direction,
+            "pattern_type": pattern_type,
+            "bulk_direction": bulk_direction,
+            "n_significant_positive": n_pos,
+            "n_significant_negative": n_neg,
+        }
+
+    def build_llm_context(self, delta: np.ndarray,
+                          path_regions: list[str] | None = None) -> str:
+        """Build a structured text context for LLM interpretation.
+
+        Args:
+            delta: (R,) ROI delta vector.
+            path_regions: optional list of brain region names the probe traversed.
+
+        Returns:
+            Formatted context string for the LLM prompt.
+        """
+        analysis = self.analyze_flow_pattern(delta)
+
+        lines = []
+        lines.append("=== ROI FLOW ANALYSIS ===\n")
+
+        # Pattern overview
+        lines.append(f"Flow pattern type: {analysis['pattern_type']}")
+        lines.append(f"Bulk information flow direction: {analysis['bulk_direction']}")
+        lines.append(f"Significant ROIs with increased activation: "
+                      f"{analysis['n_significant_positive']}")
+        lines.append(f"Significant ROIs with decreased activation: "
+                      f"{analysis['n_significant_negative']}")
+        lines.append("")
+
+        # Top receivers (positive delta)
+        if analysis["top_positive"]:
+            lines.append("TOP RECEIVING ROIs (activation INCREASED):")
+            for name, val, center in analysis["top_positive"][:8]:
+                side = "left" if center[0] < 0 else "right"
+                depth = "anterior" if center[1] > 0 else "posterior"
+                lines.append(f"  - {name} ({side}, {depth}): delta = +{val:.4f}, "
+                              f"MNI = ({center[0]:.0f}, {center[1]:.0f}, {center[2]:.0f})")
+            lines.append("")
+
+        # Top donors (negative delta)
+        if analysis["top_negative"]:
+            lines.append("TOP DONOR ROIs (activation DECREASED):")
+            for name, val, center in analysis["top_negative"][:8]:
+                side = "left" if center[0] < 0 else "right"
+                depth = "anterior" if center[1] > 0 else "posterior"
+                lines.append(f"  - {name} ({side}, {depth}): delta = {val:.4f}, "
+                              f"MNI = ({center[0]:.0f}, {center[1]:.0f}, {center[2]:.0f})")
+            lines.append("")
+
+        # Path context
+        if path_regions:
+            lines.append("MANIFOLD PATH TRAVERSED THROUGH THESE REGIONS:")
+            for i, r in enumerate(path_regions, 1):
+                lines.append(f"  {i}. {r}")
+            lines.append("")
+
+        # Directional summary
+        d = analysis["direction"]
+        lines.append("DIRECTIONAL ANALYSIS:")
+        lines.append(f"  Left-Right shift: {d['left_right']:.1f} mm "
+                      f"({'rightward' if d['left_right'] > 0 else 'leftward'})")
+        lines.append(f"  Anterior-Posterior shift: {d['anterior_posterior']:.1f} mm "
+                      f"({'anterior' if d['anterior_posterior'] > 0 else 'posterior'})")
+        lines.append(f"  Superior-Inferior shift: {d['superior_inferior']:.1f} mm "
+                      f"({'superior' if d['superior_inferior'] > 0 else 'inferior'})")
+
+        return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# ROI flow LLM interpreter
+# ---------------------------------------------------------------------------
+
+class ROIFlowLLM:
+    """Send ROI flow analysis to LLM for interpretation."""
+
+    def __init__(self, model: str = "gpt-5.4-mini", debug: bool = False):
+        self.model = model
+        self.debug = debug
+
+    def interpret_roi_flow(self, context: str) -> str:
+        """Interpret an ROI flow pattern using the LLM.
+
+        Args:
+            context: structured text from ROIFlowAnalyzer.build_llm_context()
+
+        Returns:
+            LLM interpretation text.
+        """
+        from src.region_analyzer import _ensure_ssl
+        _ensure_ssl()
+
+        from dotenv import load_dotenv
+        load_dotenv()
+
+        instructions = (
+            "You are a neuroscientist interpreting brain state dynamics from a "
+            "manifold flow simulation. The user traced a path through a learned "
+            "neural manifold (a dimensionality-reduced representation of resting-state "
+            "brain dynamics). You are given how each ROI's contribution changed along "
+            "this path.\n\n"
+            "IMPORTANT: The delta values do NOT mean regions became more or less "
+            "'active' in a simple sense. They measure how each ROI's CONTRIBUTION "
+            "to the overall brain state shifted — some regions contribute more to the "
+            "new state, some less. A positive delta means the region became a stronger "
+            "contributor; negative means it became a weaker contributor. This is a "
+            "transition in the brain's dynamic state.\n\n"
+            "Analyze what this particular state transition might mean. Do NOT list "
+            "the individual ROI changes — instead, synthesize them into ONE coherent "
+            "picture of what cognitive or neural process could underlie this specific "
+            "shift in brain dynamics. Consider the spatial pattern (which networks "
+            "gained vs lost contribution), the directionality, and what spontaneous "
+            "resting-state process would produce this exact transition.\n\n"
+            "Keep your response SHORT — 2-3 concise paragraphs maximum.\n\n"
+            "Note: ROI deltas are interpolated from a learned resting-state manifold — "
+            "interpret transitions as shifts in dynamic brain state, not literal activations."
+        )
+
+        question = context
+
+        if self.debug:
+            import sys
+            print(f"\n{'='*60}")
+            print(f"[DEBUG PROMPT] ROIFlowLLM.interpret_roi_flow")
+            print(f"{'='*60}")
+            print(f"INSTRUCTIONS:\n{instructions}")
+            print(f"\nINPUT:\n{question}")
+            print(f"{'='*60}\n")
+            sys.stdout.flush()
+
+        try:
+            from openai import OpenAI
+            client = OpenAI(timeout=60.0)
+
+            resp = client.responses.create(
+                model=self.model,
+                instructions=instructions,
+                input=question,
+                reasoning={"effort": "low"},
+                max_output_tokens=2500,
+            )
+
+            text = (resp.output_text or "").strip()
+            if text:
+                return text
+
+            if getattr(resp, "status", None) == "incomplete":
+                reason = getattr(resp.incomplete_details, "reason", "unknown")
+                return f"[GPT ERROR] Responses API incomplete: {reason}"
+
+            return "[GPT ERROR] Responses API returned no visible text."
+
+        except Exception as e:
+            import traceback
+            traceback.print_exc()
+            return f"[GPT ERROR] {e}"
+
+    def compare_two_paths(self, context_a: str, context_b: str) -> str:
+        """Compare two ROI flow patterns using the LLM.
+
+        Args:
+            context_a: structured text from path A analysis
+            context_b: structured text from path B analysis
+
+        Returns:
+            LLM comparison interpretation text.
+        """
+        from src.region_analyzer import _ensure_ssl
+        _ensure_ssl()
+
+        from dotenv import load_dotenv
+        load_dotenv()
+
+        instructions = (
+            "You are a neuroscientist comparing TWO different brain state "
+            "transitions observed in a neural manifold flow simulation. "
+            "Each path represents a different trajectory through the manifold, "
+            "producing different shifts in ROI contributions.\n\n"
+            "You are given the ROI flow analysis for Path A and Path B.\n\n"
+            "Compare them: What is SIMILAR between the two transitions? "
+            "What is DIFFERENT? Which cognitive or neural processes might "
+            "explain the divergence? Which path represents a more dramatic "
+            "state change? Are they transitions within the same network or "
+            "do they involve fundamentally different networks?\n\n"
+            "Keep your response SHORT — 2-3 concise paragraphs maximum.\n\n"
+            "Note: both paths are trajectories through a learned resting-state manifold — "
+            "compare them as different dynamic regimes, not literal biological events."
+        )
+
+        question = (
+            "=== PATH A ===\n" + context_a + "\n\n"
+            "=== PATH B ===\n" + context_b
+        )
+
+        if self.debug:
+            import sys
+            print(f"\n{'='*60}")
+            print(f"[DEBUG PROMPT] ROIFlowLLM.compare_two_paths")
+            print(f"{'='*60}")
+            print(f"INSTRUCTIONS:\n{instructions}")
+            print(f"\nINPUT:\n{question}")
+            print(f"{'='*60}\n")
+            sys.stdout.flush()
+
+        try:
+            from openai import OpenAI
+            client = OpenAI(timeout=90.0)
+
+            resp = client.responses.create(
+                model=self.model,
+                instructions=instructions,
+                input=question,
+                reasoning={"effort": "low"},
+                max_output_tokens=3000,
+            )
+
+            text = (resp.output_text or "").strip()
+            if text:
+                return text
+            return "[GPT ERROR] No response text."
+
+        except Exception as e:
+            import traceback
+            traceback.print_exc()
+            return f"[GPT ERROR] {e}"

requirements.txt

@@ -0,0 +1,6 @@
+fastapi==0.115.6
+uvicorn[standard]==0.34.0
+numpy==2.2.1
+scipy==1.15.1
+python-dotenv==1.0.1
+openai==1.59.6