From c157bd0ecef3557c3d096631b225a887ae5676fb Mon Sep 17 00:00:00 2001
From: Matteo Visconti di Oleggio Castello <mvdoc@berkeley.edu>
Date: Sat, 19 Sep 2026 17:27:38 -0700
Subject: [PATCH 1/5] ENH render Tractogram streamlines in the WebGL viewer

Streamlines bypass the mosaic and CTM machinery entirely. Package collects
each Tractogram into four little-endian buffers -- points, offsets, colors and
group membership -- served by a new TractHandler under /tract/, or written to
tracts/*.bin by make_static. Colors arrive finished, since the colormapping
happens in Python, so the browser side stays simple.

resources/js/tractogram.js builds one THREE.Line in LinePieces mode per
tractogram, with a Uint16 or Uint32 index depending on size and a
duplicated-vertex fallback where OES_element_index_uint is missing. The
controls live in their own #tracts panel under the dataset box rather than in
dat.gui, because what a tractogram shows is data: a visibility checkbox and an
opacity slider per tractogram, plus a checkbox per bundle when the file has
groups. A streamline draws while it belongs to at least one checked group.

Three things about Three.js r69 that this had to work around, each of which
looked like a rendering bug first:

- svgoverlay.js renders a depth pass with scene.overrideMaterial, which the
  line geometry cannot satisfy; tract objects opt out through
  userData.skipOverrideMaterial or r69 throws on the missing attributes.
- r69 walks the transparent list backwards, so a translucent tractogram needs
  a large renderDepth to stay behind the surface rather than on top of it.
- The material keeps writing depth at every opacity. Without it the
  streamlines have nothing to depth-test against each other and blend in
  buffer order, so the bundle last in the geometry paints over those in front
  and the apparent depth order changes as the opacity slider moves.

Streamlines hide as soon as the surface starts to inflate or flatten, since
their coordinates only mean anything against the folded surface, and a
tractogram alone cannot open a viewer -- Package says so rather than failing
obscurely later.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 cortex/tests/test_webgl_tractogram.py   | 239 ++++++++++
 cortex/webgl/data.py                    | 138 +++++-
 cortex/webgl/mixer.html                 |   6 +-
 cortex/webgl/resources/css/mriview.css  |  95 ++++
 cortex/webgl/resources/js/mriview.js    |  97 +++-
 cortex/webgl/resources/js/svgoverlay.js |  13 +
 cortex/webgl/resources/js/tractogram.js | 598 ++++++++++++++++++++++++
 cortex/webgl/static.html                |   6 +-
 cortex/webgl/template.html              |   2 +
 cortex/webgl/view.py                    |  70 ++-
 docs/dataset.rst                        |   2 +
 11 files changed, 1248 insertions(+), 18 deletions(-)
 create mode 100644 cortex/tests/test_webgl_tractogram.py
 create mode 100644 cortex/webgl/resources/js/tractogram.js

diff --git a/cortex/tests/test_webgl_tractogram.py b/cortex/tests/test_webgl_tractogram.py
new file mode 100644
index 000000000..466f3962a
--- /dev/null
+++ b/cortex/tests/test_webgl_tractogram.py
@@ -0,0 +1,239 @@
+"""Tests for shipping a `cortex.Tractogram` to the WebGL viewer.
+
+Covers the python transport (`cortex.webgl.data.Package`, `make_static`) and,
+when playwright + Chromium are available, the javascript side
+(`resources/js/tractogram.js`).
+"""
+
+import os
+
+import numpy as np
+import pytest
+
+import cortex
+from cortex.webgl.data import Package
+
+from .testing_utils import has_playwright
+from .test_tractogram import _make_tractogram, _overlapping_groups
+
+subj = "S1"
+
+
+def _vertex():
+    """A small Vertex dataview for S1, to accompany the tractogram."""
+    pts, _ = cortex.db.get_surf(subj, "fiducial", merge=True)
+    return cortex.Vertex(np.zeros(pts.shape[0], dtype=np.float32), subj)
+
+
+def _dataset():
+    # Overlapping groups + an ungrouped streamline, to exercise the viewer's
+    # per-group visibility toggles (a streamline is visible iff it is a
+    # member of >=1 visible group; ungrouped streamlines follow a pseudo
+    # "(ungrouped)" group).
+    tract = _make_tractogram(
+        n_streamlines=8, n_points=15, groups=_overlapping_groups(8)
+    )
+    return cortex.Dataset(overlay=_vertex(), af=tract), tract
+
+
+# ---------------------------------------------------------------------------
+# Package: wire format
+# ---------------------------------------------------------------------------
+
+
+def test_package_tract_metadata_and_buffers():
+    ds, tract = _dataset()
+    pkg = Package(ds)
+
+    meta = pkg.metadata()
+    assert "af" in meta["tracts"]
+    tmeta = meta["tracts"]["af"]
+
+    assert tmeta["subject"] == subj
+    assert tmeta["n_points"] == tract.n_points
+    assert tmeta["n_streamlines"] == tract.n_streamlines
+    assert tmeta["alpha"] == tract.alpha
+    assert tmeta["linewidth"] == tract.linewidth
+    assert tmeta["visible"] is True
+    assert set(tmeta["urls"]) == {"points", "offsets", "colors", "groups"}
+    assert tmeta["urls"]["points"] == "/tract/af/points/"
+
+    bufs = pkg.tracts["af"]
+    n, m = tract.n_points, tract.n_streamlines
+    n_group_entries = sum(len(idx) for idx in tract.groups.values())
+    assert len(bufs["points"]) == 12 * n
+    assert len(bufs["offsets"]) == 4 * (m + 1)
+    assert len(bufs["colors"]) == 3 * n
+    assert len(bufs["groups"]) == 4 * n_group_entries
+
+    # The buffers must round-trip as little-endian arrays of the right dtype.
+    points = np.frombuffer(bufs["points"], dtype="<f4").reshape(-1, 3)
+    assert np.allclose(points, tract.points)
+    offsets = np.frombuffer(bufs["offsets"], dtype="<u4")
+    assert np.array_equal(offsets, tract.offsets)
+    assert offsets[-1] == n
+
+    # Metadata "groups" is {name: [start, stop]} slicing into the buffer,
+    # contiguous and in the same order as `tract.groups`.
+    group_buf = np.frombuffer(bufs["groups"], dtype="<u4")
+    assert tmeta["groups"].keys() == tract.groups.keys()
+    pos = 0
+    for name, idx in tract.groups.items():
+        start, stop = tmeta["groups"][name]
+        assert (start, stop) == (pos, pos + len(idx))
+        assert stop - start == len(idx)
+        np.testing.assert_array_equal(group_buf[start:stop], idx)
+        pos += len(idx)
+
+
+def test_package_empty_groups_gives_empty_buffer():
+    tract = _make_tractogram(n_streamlines=4, n_points=10, groups={})
+    pkg = Package(cortex.Dataset(af=tract), require_brains=False)
+
+    assert pkg.tracts["af"]["groups"] == b""
+    meta = pkg.metadata()
+    assert meta["tracts"]["af"]["groups"] == {}
+
+
+def test_package_keeps_tracts_out_of_views_and_data():
+    """Every existing javascript path must see exactly what it saw before."""
+    ds, tract = _dataset()
+    pkg = Package(ds)
+    meta = pkg.metadata()
+
+    assert [view["name"] for view in meta["views"]] == ["overlay"]
+    assert "af" not in meta["data"]
+    assert "af" not in meta["images"]
+    assert tract.name not in meta["data"]
+    # ... and the tractogram is not among the BrainData that get reordered.
+    assert all(not isinstance(u, cortex.Tractogram) for u in pkg.uniques)
+
+
+def test_package_reorder_ignores_tracts():
+    tract = _make_tractogram(n_streamlines=8, n_points=15)
+    pkg = Package(cortex.Dataset(af=tract), require_brains=False)
+    before = pkg.tracts["af"]["points"]
+    # reorder() needs a per-subject CTM index for every BrainData it holds;
+    # with only a tractogram there is nothing to reorder, so no index is
+    # needed and the buffers must come out untouched.
+    pkg.reorder({})
+    assert pkg.tracts["af"]["points"] == before
+
+
+def test_package_tractogram_only_raises():
+    tract = _make_tractogram(n_streamlines=4, n_points=10)
+    with pytest.raises(ValueError, match="cannot be displayed on its own"):
+        Package(cortex.Dataset(af=tract))
+    with pytest.raises(ValueError, match="cannot be displayed on its own"):
+        Package(tract)
+
+    # A running viewer can still be handed a tractogram alone.
+    pkg = Package(cortex.Dataset(af=tract), require_brains=False)
+    assert "af" in pkg.tracts
+
+
+# ---------------------------------------------------------------------------
+# make_static
+# ---------------------------------------------------------------------------
+
+
+def test_make_static_writes_tract_buffers(tmp_path):
+    ds, tract = _dataset()
+    outpath = str(tmp_path / "static")
+    cortex.webgl.make_static(outpath, ds, recache=False)
+
+    n, m = tract.n_points, tract.n_streamlines
+    n_group_entries = sum(len(idx) for idx in tract.groups.values())
+    expected = {
+        "af_points.bin": 12 * n,
+        "af_offsets.bin": 4 * (m + 1),
+        "af_colors.bin": 3 * n,
+        "af_groups.bin": 4 * n_group_entries,
+    }
+    for fname, size in expected.items():
+        path = os.path.join(outpath, "tracts", fname)
+        assert os.path.exists(path), "%s was not written" % fname
+        assert os.path.getsize(path) == size
+
+    with open(os.path.join(outpath, "index.html")) as fp:
+        html = fp.read()
+    assert "tracts/af_points.bin" in html
+
+
+# ---------------------------------------------------------------------------
+# Headless browser
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.skipif(
+    not has_playwright, reason="playwright + Chromium not available"
+)
+def test_tractogram_renders_in_headless_viewer():
+    ds, tract = _dataset()
+
+    with cortex.export.headless_viewer(ds, viewer_params={}) as handle:
+        # `handle` is a JSProxy rooted at window.viewer: attribute access
+        # queries the live javascript object graph over the websocket.
+        # The tracts load asynchronously and deliberately do not block
+        # viewer.loaded, so poll until the geometry has been built
+        # (Tractogram.n_points stays 0 until then).
+        import time
+
+        deadline = time.monotonic() + 30
+        n_points = 0
+        while time.monotonic() < deadline:
+            n_points = handle.tracts.af.n_points
+            if n_points:
+                break
+            time.sleep(0.2)
+
+        n, m = tract.n_points, tract.n_streamlines
+        assert n_points == n
+        assert handle.tracts.af.n_streamlines == m
+        assert handle.tracts.af.object.visible is True
+        # Controls now live in a dedicated DOM panel (#tracts) instead of a
+        # dat.gui folder: just confirm the per-tractogram element was built.
+        assert "element" in dir(handle.tracts.af)
+        # Either the indexed geometry (one vertex per point) or the
+        # duplicated-vertex fallback (two per segment).
+        full_n_vertices = handle.tracts.af.n_vertices
+        assert full_n_vertices in (n, 2 * (n - m))
+
+        # Per-group visibility: hiding "first_half" must shrink the drawn
+        # geometry (fewer visible streamlines -> fewer segments; on the
+        # indexed path only the index shrinks, so count segments rather
+        # than vertices), and showAllGroups() must restore it. JSProxy calls
+        # return the per-client response list, hence the [0].
+        full_n_segments = handle.tracts.af.n_segments
+        assert full_n_segments == n - m
+        assert set(handle.tracts.af.groupNames()[0]) == {
+            "first_half",
+            "second_half",
+            "(ungrouped)",
+        }
+        handle.tracts.af.setGroupVisible("first_half", False)
+        shrunk_n_segments = handle.tracts.af.n_segments
+        assert 0 < shrunk_n_segments < full_n_segments
+
+        handle.tracts.af.showAllGroups()
+        assert handle.tracts.af.n_segments == full_n_segments
+
+        # Translucent streamlines must keep writing depth. Without it they
+        # have nothing to depth-test against each other and blend in buffer
+        # order, so whichever bundle sits last in the geometry paints over
+        # the ones in front of it and the picture reorders itself the moment
+        # opacity leaves 1.
+        assert handle.tracts.af.material.depthWrite is True
+        handle.tracts.af.setOpacity(0.5)
+        assert handle.tracts.af.material.transparent is True
+        assert handle.tracts.af.material.depthWrite is True
+        # Called with no argument setOpacity is the getter; as with
+        # groupNames() above, a JSProxy call answers with the per-client
+        # response list.
+        assert handle.tracts.af.setOpacity()[0] == 0.5
+        # Out-of-range and unparsable input is clamped / ignored rather than
+        # reaching the material (the panel's number box accepts typing).
+        handle.tracts.af.setOpacity(5)
+        assert handle.tracts.af.setOpacity()[0] == 1
+        handle.tracts.af.setOpacity("")
+        assert handle.tracts.af.setOpacity()[0] == 1
diff --git a/cortex/webgl/data.py b/cortex/webgl/data.py
index 0dfed7d4c..66e70412b 100644
--- a/cortex/webgl/data.py
+++ b/cortex/webgl/data.py
@@ -5,7 +5,20 @@
     views = [ dict(name="proper name", cmap=cmap, vmin=vmin, vmax=vmax, data=["__braindata_name"]) ],
     data  = dict(__braindata_name=dict(subject=subject, min=min, max=max)),
     images=(__braindata_name=["img1.png", "img2.png"]),
+    tracts = dict(name=dict(subject=subject, n_points=N, n_streamlines=M, ...,
+                            urls=dict(points=url, offsets=url, colors=url))),
 )
+
+Tractograms (`cortex.Tractogram`) are handled separately from the BrainData
+based dataviews: they are not colormapped in the browser and carry no
+volume/vertex arrays, so they never appear in ``views``/``data``/``images``.
+Instead they contribute four little-endian binary buffers each -- ``points``
+(float32, N x 3), ``offsets`` (uint32, M + 1), ``colors`` (uint8, N x 3) and
+``groups`` (uint32, concatenation of every group's streamline indices, in
+the order they appear in ``tract_meta[name]["groups"]``, whose values are
+``[start, stop]`` slice bounds into this buffer rather than counts) -- which
+the viewer fetches and turns into a THREE.js line geometry
+(``resources/js/tractogram.js``).
 """
 
 import os
@@ -19,12 +32,68 @@
 
 # TODO: How to package multiviews?
 class Package(object):
-    """Package the data into a form usable by javascript"""
+    """Package the data into a form usable by javascript
+
+    Parameters
+    ----------
+    data : Dataset or Dataview
+        The data to package.
+    require_brains : bool
+        If True (the default), packaging a dataset that holds only
+        tractograms raises `ValueError`: the viewer cannot boot without a
+        Volume/Vertex dataview to build its surfaces from. Set to False when
+        pushing data into an already-running viewer.
+    """
 
-    def __init__(self, data):
+    def __init__(self, data, require_brains=True):
         self.dataset = dataset.normalize(data)
-        self.uniques = list(data.uniques(collapse=True))
-        self.subjects = set()
+        self._require_brains = require_brains
+
+        # `normalize` returns a bare Dataview untouched (it does not wrap it
+        # into a Dataset), so handle both shapes here.
+        if isinstance(self.dataset, dataset.Dataset):
+            items = list(self.dataset)
+        else:
+            items = [(None, self.dataset)]
+
+        # Tractograms are not BrainData: they are pulled out first, both
+        # because Dataset.uniques() would choke on them (only BrainData
+        # implements .uniques()) and because every existing javascript path
+        # expects views/data/images to hold colormapped brain data only.
+        self.tracts = dict()
+        self.tract_meta = dict()
+        brain_views = []
+        for name, view in items:
+            if isinstance(view, dataset.Tractogram):
+                tname = name or view.description or view.name
+                if view.n_points > np.iinfo(np.uint32).max:
+                    raise ValueError(
+                        "Tractogram %r has %d points, more than the uint32 "
+                        "offsets sent to the viewer can address; use "
+                        "Tractogram.subsample() first." % (tname, view.n_points)
+                    )
+                group_indices, _ = view.groups_wire()
+                self.tracts[tname] = dict(
+                    points=view.points.astype("<f4").tobytes(),
+                    offsets=view.offsets.astype("<u4").tobytes(),
+                    colors=view.vertex_colors().astype(np.uint8).tobytes(),
+                    groups=group_indices.astype("<u4").tobytes(),
+                )
+                self.tract_meta[tname] = view.to_json()
+            else:
+                brain_views.append(view)
+
+        # Deduplicate while keeping the dataset order (BrainData hashes by
+        # identity, so a plain set would shuffle the brains between runs).
+        self.uniques = []
+        for view in brain_views:
+            for sv in view.uniques(collapse=True):
+                if sv not in self.uniques:
+                    self.uniques.append(sv)
+        # Tract subjects count too: `show` builds CTM packs per subject,
+        # `addData` rejects unknown subjects and `make_static(anonymize=True)`
+        # renames every subject it knows about.
+        self.subjects = set(meta["subject"] for meta in self.tract_meta.values())
 
         self.brains = dict()
         self.images = dict()
@@ -75,10 +144,18 @@ def __init__(self, data):
                 self.brains[name]["mosaic"] = self.images[name][0][1]
                 self.images[name] = [_pack_png(m) for m, shape in self.images[name]]
 
+        if require_brains and self.tracts and not self.brains:
+            raise ValueError(
+                "A Tractogram cannot be displayed on its own: the webgl "
+                "viewer needs at least one Volume or Vertex dataview to "
+                "build the surfaces and boot. Pass them together, e.g. "
+                "cortex.webshow(cortex.Dataset(curvature=vertex, af=tract))."
+            )
+
     @property
     def views(self):
         metadata = []
-        for name, view in self.dataset:
+        for name, view in self._brain_items():
             meta = view.to_json(simple=False)
             meta["name"] = name
             if "stim" in meta["attrs"]:
@@ -86,7 +163,21 @@ def views(self):
             metadata.append(meta)
         return metadata
 
+    def _brain_items(self):
+        """(name, dataview) pairs, excluding tractograms."""
+        if isinstance(self.dataset, dataset.Dataset):
+            items = list(self.dataset)
+        else:
+            items = [(self.dataset.description or "data", self.dataset)]
+        return [
+            (name, view)
+            for name, view in items
+            if not isinstance(view, dataset.Tractogram)
+        ]
+
     def reorder(self, subjects):
+        # Tractograms carry no vertex-indexed data, so there is nothing to
+        # reorder for them; `self.uniques` holds BrainData only.
         indices = dict(
             (k, np.load(os.path.splitext(v)[0] + ".npz")) for k, v in subjects.items()
         )
@@ -104,13 +195,37 @@ def reorder(self, subjects):
         for npz in indices.values():
             npz.close()
 
-    def metadata(self, submap=None, **kwargs):
+    def metadata(self, submap=None, tract_fmt="/tract/{name}/{buf}/", **kwargs):
+        """Assemble the metadata dict handed to the javascript viewer.
+
+        Parameters
+        ----------
+        submap : dict or None
+            Optional subject renaming map (used by `make_static` when
+            anonymizing).
+        tract_fmt : str
+            Format string for the tractogram buffer urls, with ``{name}``
+            (tractogram name) and ``{buf}`` (one of points/offsets/colors)
+            fields. Defaults to the live-server route served by
+            `cortex.webgl.view.TractHandler`.
+        kwargs
+            Passed to `image_names` (i.e. its ``fmt``).
+        """
         if submap is not None:
             for data in self.brains.values():
                 data["subject"] = submap[data["subject"]]
-        return dict(
+            for meta in self.tract_meta.values():
+                if meta["subject"] in submap:
+                    meta["subject"] = submap[meta["subject"]]
+        meta = dict(
             views=self.views, data=self.brains, images=self.image_names(**kwargs)
         )
+        urls = self.tract_names(fmt=tract_fmt)
+        meta["tracts"] = dict(
+            (name, dict(self.tract_meta[name], urls=urls[name]))
+            for name in self.tracts
+        )
+        return meta
 
     def image_names(self, fmt="/data/{name}/{frame}/"):
         names = dict()
@@ -118,6 +233,15 @@ def image_names(self, fmt="/data/{name}/{frame}/"):
             names[name] = [fmt.format(name=name, frame=i) for i in range(len(imgs))]
         return names
 
+    def tract_names(self, fmt="/tract/{name}/{buf}/"):
+        """Urls of the binary buffers of every tractogram, keyed by name."""
+        names = dict()
+        for name, bufs in self.tracts.items():
+            names[name] = dict(
+                (buf, fmt.format(name=name, buf=buf)) for buf in sorted(bufs)
+            )
+        return names
+
 
 def _pack_png(mosaic):
     from PIL import Image
diff --git a/cortex/webgl/mixer.html b/cortex/webgl/mixer.html
index b83e96203..5a197162c 100644
--- a/cortex/webgl/mixer.html
+++ b/cortex/webgl/mixer.html
@@ -1,7 +1,7 @@
 {% autoescape None %}
 {% extends template.html %}
 {% block jsinit %}
-    var viewer, subjects, datasets, figure, sock, viewopts;
+    var viewer, subjects, datasets, figure, sock, viewopts, metadata;
 {% end %}
 {% block onload %}
         viewopts = {{viewopts}};
@@ -19,8 +19,10 @@
         };
         {% end %}
 
-        dataviews = dataset.fromJSON({{data}});
+        metadata = {{data}};
+        dataviews = dataset.fromJSON(metadata);
         viewer.addData(dataviews);
+        viewer.addTracts(metadata.tracts);
 
         sock = new Websock();
 {% end %}
diff --git a/cortex/webgl/resources/css/mriview.css b/cortex/webgl/resources/css/mriview.css
index 2a08c683a..a19cfba7b 100644
--- a/cortex/webgl/resources/css/mriview.css
+++ b/cortex/webgl/resources/css/mriview.css
@@ -127,6 +127,101 @@ a:visited { color:white; }
     font-size:24pt;
     font-weight:bold;
 }
+
+/* Tractogram controls, under the dataset box */
+.tracts-panel {
+    position:absolute;
+    z-index:8;
+    padding:10px 15px;
+    margin:20px;
+    border-radius:10px;
+    background:rgba(255,255,255,.2);
+    width:max-content;
+    min-width:200px;
+    max-width:90vw;
+    max-height:60vh;
+    overflow-y:auto;
+    overflow-x:hidden;
+    color:white;
+    font-family:Helvetica Neue, sans-serif;
+    font-size:10pt;
+    display:none;
+}
+.tract-item + .tract-item {
+    margin-top:8px;
+    padding-top:8px;
+    border-top:1px solid rgba(255,255,255,.3);
+}
+.tract-header {
+    display:flex;
+    align-items:center;
+    cursor:default;
+}
+.tract-header .tract-toggle {
+    cursor:pointer;
+    width:1.2em;
+    display:inline-block;
+    text-align:center;
+    user-select:none;
+    color:#DDD;
+}
+.tract-header .tract-name {
+    font-weight:bold;
+    margin-left:4px;
+    white-space:nowrap;
+    overflow:hidden;
+    text-overflow:ellipsis;
+}
+.tract-header input[type=checkbox] {
+    margin:0 4px 0 0;
+}
+.tract-body {
+    margin:6px 0 0 1.2em;
+}
+.tract-opacity-row {
+    display:flex;
+    align-items:center;
+    margin-bottom:4px;
+}
+.tract-opacity-row label {
+    margin-right:6px;
+    color:#CCC;
+}
+.tract-opacity-row input[type=range] {
+    flex:1 1 auto;
+    max-width:110px;
+}
+.tract-opacity-row input.tract-opacity-value {
+    flex:0 0 auto;
+    width:46px;
+    margin-left:6px;
+    background:rgba(0,0,0,0.35);
+    border:1px solid #666;
+    color:#EEE;
+    font-size:11px;
+    padding:1px 2px;
+}
+.tract-groups-actions {
+    margin-bottom:2px;
+}
+.tract-groups-actions a {
+    color:#9CF;
+    cursor:pointer;
+    text-decoration:underline;
+    margin-right:8px;
+}
+.tract-group-row {
+    white-space:nowrap;
+    overflow:hidden;
+    text-overflow:ellipsis;
+}
+.tract-group-row input[type=checkbox] {
+    margin:0 4px 0 0;
+}
+.tract-group-count {
+    color:#AAA;
+    font-size:8pt;
+}
 #helpmenu {
     position:absolute;
     z-index:8;
diff --git a/cortex/webgl/resources/js/mriview.js b/cortex/webgl/resources/js/mriview.js
index 790bb4135..88512e5d0 100644
--- a/cortex/webgl/resources/js/mriview.js
+++ b/cortex/webgl/resources/js/mriview.js
@@ -62,6 +62,12 @@ var mriview = (function(module) {
         //mix function to attach to surface when it's added
         this._mix = function(evt){
             this.controls.setMix(evt.flat);
+            //Streamlines live in fiducial space: hide them as soon as the
+            //surface starts inflating or flattening. Every path that changes
+            //the morph (unfold slider, python _set_view, Viewer.setMix)
+            //ends up dispatching this event.
+            for (var name in this.tracts)
+                this.tracts[name].setMix(evt.mix);
         }.bind(this);
 
         //allowTilt function to attach to surface when it's added
@@ -104,6 +110,8 @@ var mriview = (function(module) {
 
         this.surfs = [];
         this.dataviews = {};
+        //mriview.Tractogram objects, keyed by name (see addTracts)
+        this.tracts = {};
         this.active = null;
 
         this.loaded = $.Deferred().done(function() {
@@ -274,10 +282,17 @@ var mriview = (function(module) {
         //(see JSMixer.addData in cortex/webgl/view.py). It is recognizable
         //by its "images" key, and has to be turned into DataView objects
         //(which also registers the new BrainData in dataset.brains).
-        if (!(data instanceof Array) && data.images !== undefined)
+        var tracts;
+        if (!(data instanceof Array) && data.images !== undefined) {
+            //Streamlines travel next to the dataviews in the same package, but
+            //they are not dataviews (see cortex/webgl/data.py).
+            tracts = data.tracts;
             data = dataset.fromJSON(data);
+        }
         if (!(data instanceof Array))
             data = [data];
+        if (tracts !== undefined)
+            this.addTracts(tracts);
 
         var name, view, ui;
 
@@ -303,7 +318,10 @@ var mriview = (function(module) {
             // this.dataui.addFolder(name, true, view.ui);
         }
 
-        this.setData(data[0].name);
+        //A python-side addData() push can carry tractograms only, in which
+        //case the currently displayed dataview stays put.
+        if (data.length > 0)
+            this.setData(data[0].name);
     };
 
     module.Viewer.prototype.fitDataname = function() {
@@ -709,6 +727,7 @@ var mriview = (function(module) {
                 $("#dataopts").show();
             }
             this.fitDataname();
+            this._updateTractsPanel();
             this.schedule();
             this.loaded.resolve();
 
@@ -745,6 +764,70 @@ var mriview = (function(module) {
                 $(this).remove();
         })
     };
+    module.Viewer.prototype.addTracts = function(meta) {
+        //`meta` is the `tracts` dict of the metadata package built by
+        //cortex/webgl/data.py: {name: {..., urls:{points, offsets, colors}}}.
+        if (meta === undefined || meta === null)
+            return;
+
+        for (var name in meta) {
+            if (this.tracts[name] !== undefined)
+                this.rmTracts(name);
+
+            var tract = new module.Tractogram(name, meta[name], this.renderer);
+            this.tracts[name] = tract;
+            this.root.add(tract.object);
+            //Tracts load asynchronously and the viewer's own `loaded` Deferred
+            //deliberately does not wait for them, so redraw when they land.
+            tract.loaded.done(function(tract) {
+                $(this.object).find("#tracts").append(tract.element);
+                this._updateTractsPanel();
+                this.schedule();
+            }.bind(this));
+            //Keep a freshly added tract in step with the current morph state.
+            if (tract.setMix !== undefined && this.surfs.length > 0)
+                tract.setMix(this.setMix());
+        }
+        this.schedule();
+    };
+
+    module.Viewer.prototype.rmTracts = function(name) {
+        var tract = this.tracts[name];
+        if (tract === undefined)
+            return;
+        this.root.remove(tract.object);
+        if (tract.element !== null)
+            tract.element.remove();
+        tract.dispose();
+        delete this.tracts[name];
+        this._updateTractsPanel();
+        this.schedule();
+    };
+
+    //Show/hide the #tracts panel depending on whether there is anything to
+    //show, and keep it positioned directly under the dataset box (#dataopts
+    //can change height -- a long description, or being hidden entirely --
+    //so this is recomputed rather than fixed in CSS).
+    module.Viewer.prototype._updateTractsPanel = function() {
+        var panel = $(this.object).find("#tracts");
+        if (panel.length === 0)
+            return;
+        var hasTracts = Object.keys(this.tracts).length > 0;
+        panel.toggle(hasTracts);
+        if (!hasTracts)
+            return;
+
+        var dataopts = $(this.object).find("#dataopts");
+        if (dataopts.length && dataopts.is(":visible")) {
+            panel.css({
+                left: dataopts.position().left,
+                top: dataopts.position().top + dataopts.outerHeight() + 10,
+            });
+        } else {
+            panel.css({left: "", top: ""});
+        }
+    };
+
     module.Viewer.prototype.addSurf = function(surftype, opts) {
         //Sets the slicing surface used to visualize the data
         var surf = new surftype(this.active, opts);
@@ -964,6 +1047,7 @@ var mriview = (function(module) {
         for (var i = 0; i < this.surfs.length; i++)
             if (this.surfs[i].setMix !== undefined)
                 this.surfs[i].setMix(mix);
+        //Tracts follow through the surfaces' "mix" event (see this._mix).
     }
 
     module.Viewer.prototype.pick = function(evt) {
@@ -1169,7 +1253,7 @@ var mriview = (function(module) {
     var _bound = false;
     module.Viewer.prototype._bindUI = function() {
         $(window).scrollTop(0);
-        $(window).resize(function() { this.resize(); this.fitDataname(); }.bind(this));
+        $(window).resize(function() { this.resize(); this.fitDataname(); this._updateTractsPanel(); }.bind(this));
         this.canvas.resize(function() { this.resize(); }.bind(this));
 
         var cam_ui = this.ui.addFolder("camera", true);
@@ -1431,8 +1515,11 @@ var mriview = (function(module) {
         var dataset_cat = $(dataopts).find('#dataset_category');
         dataset_cat.hide();
         $(dataopts).find('#dataname').click(function(e) {
-          dataset_cat.slideToggle();
-        });
+          dataset_cat.slideToggle({
+              step: function() { this._updateTractsPanel(); }.bind(this),
+              complete: function() { this._updateTractsPanel(); }.bind(this),
+          });
+        }.bind(this));
 
         var setdat = function(event, ui) {
             var names = [];
diff --git a/cortex/webgl/resources/js/svgoverlay.js b/cortex/webgl/resources/js/svgoverlay.js
index c9ccaca68..a9f756ca7 100644
--- a/cortex/webgl/resources/js/svgoverlay.js
+++ b/cortex/webgl/resources/js/svgoverlay.js
@@ -157,9 +157,22 @@ var svgoverlay = (function(module) {
             var clearAlpha = renderer.getClearAlpha();
             var clearColor = renderer.getClearColor().clone();
             renderer.setClearColor(0xffffff, 1);
+            //The depth shader only knows the surface's vertex attributes, so
+            //objects that opt out (e.g. tractography lines, see tractogram.js)
+            //are hidden for this pass -- rendering them with the override
+            //material would crash on the missing attributes.
+            var hidden = [];
+            scene.traverse(function(obj) {
+                if (obj.visible && obj.userData && obj.userData.skipOverrideMaterial) {
+                    obj.visible = false;
+                    hidden.push(obj);
+                }
+            });
             scene.overrideMaterial = this.depthshade;
             renderer.render(scene, camera, this.depth);
             scene.overrideMaterial = null;
+            for (var i = 0; i < hidden.length; i++)
+                hidden[i].visible = true;
             renderer.setClearColor(clearColor, clearAlpha);
             this.labels.left.visible = true;
             this.labels.right.visible = true;
diff --git a/cortex/webgl/resources/js/tractogram.js b/cortex/webgl/resources/js/tractogram.js
new file mode 100644
index 000000000..032eb2fe2
--- /dev/null
+++ b/cortex/webgl/resources/js/tractogram.js
@@ -0,0 +1,598 @@
+var mriview = (function(module) {
+
+    //Fetch a binary payload (one of the tractogram's buffers) as an
+    //ArrayBuffer. Same XMLHttpRequest style as surfload.js / CTMLoader.js.
+    function loadBuffer(url, callback, errback) {
+        var xhr = new XMLHttpRequest();
+        xhr.onreadystatechange = function() {
+            if (xhr.readyState == 4) {
+                if (xhr.status == 200 || xhr.status == 206 || xhr.status == 0) {
+                    callback(xhr.response);
+                } else {
+                    console.error("mriview.Tractogram: couldn't load " + url +
+                                  " (" + xhr.status + ")");
+                    if (errback !== undefined)
+                        errback(xhr.status);
+                }
+            }
+        };
+        xhr.open("GET", url, true);
+        xhr.responseType = "arraybuffer";
+        xhr.send(null);
+    }
+
+    //Three.js r69 only enables 32-bit element indices when the
+    //OES_element_index_uint extension is present (see the THREE.Line branch of
+    //renderBufferDirect, three.js:20451, which picks UNSIGNED_INT purely from
+    //the array type -- an unsupported extension means a GL error rather than a
+    //fallback). Without it we duplicate the vertices instead, which also avoids
+    //needing r69's `geometry.offsets` drawcall chunking for >65535 vertices.
+    module.supportsUint32Index = function(renderer) {
+        var gl = null;
+        if (renderer !== undefined && renderer !== null)
+            gl = renderer.context;
+        else if (window.viewer !== undefined && window.viewer.renderer !== undefined)
+            gl = window.viewer.renderer.context;
+
+        if (gl === null || gl === undefined)
+            return false;
+        try {
+            return !!gl.getExtension("OES_element_index_uint");
+        } catch (e) {
+            return false;
+        }
+    };
+
+    //A bundle of streamlines, rendered as GL_LINES.
+    //
+    //`meta` is one entry of the `tracts` dict of the metadata package built by
+    //cortex/webgl/data.py: {subject, n_points, n_streamlines, alpha, linewidth,
+    //visible, color, groups: {name: [start, stop]}, description,
+    //urls:{points, offsets, colors, groups}}.
+    module.Tractogram = function(name, meta, renderer) {
+        this.name = name;
+        this.meta = meta;
+        this.renderer = renderer;
+
+        this._visible = (meta.visible === undefined) ? true : !!meta.visible;
+        this._opacity = (meta.alpha === undefined) ? 1 : meta.alpha;
+        this._mix = 0;
+
+        this.n_points = 0;
+        this.n_streamlines = 0;
+        //Number of vertices actually uploaded to the GPU: equals n_points
+        //for the indexed geometry, 2 * (number of segments) for the
+        //duplicated-vertex fallback. Plain numbers are also what the python
+        //JSProxy can read back (typed-array lengths are not enumerable).
+        this.n_vertices = 0;
+        this.geometry = null;
+        this.material = null;
+        this.line = null;
+
+        //Per-group visibility (name -> bool), including a synthetic
+        //"(ungrouped)" entry when at least one streamline belongs to no
+        //named group. Populated once the "groups" buffer has loaded (see
+        //_build); empty until then, and left empty forever when the
+        //tractogram has no groups at all (n.b. distinct from "has groups
+        //but is entirely covered by them", which does not create the
+        //pseudo-group). this._hasGroups records whether group filtering
+        //applies at all, so setVisible-only tractograms skip it entirely.
+        this._hasGroups = false;
+        this._groupVisible = {};
+        //Uint32Array: concatenation of every real group's streamline
+        //indices (server "groups" buffer) followed by the synthetic
+        //"(ungrouped)" group's indices, if any -- see _build.
+        this._groupIndices = null;
+        //name -> [start, stop] slice into _groupIndices.
+        this._groupSlices = {};
+        //Uint8Array of length n_streamlines, recomputed by
+        //_updateStreamlineVisibility whenever _groupVisible changes: 1 if
+        //the streamline is a member of >=1 visible group (or, with no
+        //groups at all, always 1).
+        this._streamlineVisible = null;
+        //Raw (unfiltered) buffers, kept around so _rebuildGeometry can
+        //recompute the segment index / duplicated arrays without re-fetching.
+        this._rawPoints = null;
+        this._rawOffsets = null;
+        this._rawColors = null;
+
+        //The viewer's own `loaded` Deferred must NOT wait on this one: tracts
+        //are an overlay on top of a viewer that is usable without them.
+        this.loaded = $.Deferred();
+
+        this.object = new THREE.Group();
+        this.object.name = "Tractogram:" + name;
+        this.object.visible = this._visible;
+        //Passes that render the scene with a surface-specific override
+        //material (the SVG label depth pass in svgoverlay.js) must skip us:
+        //those shaders expect surface attributes this geometry doesn't have.
+        this.object.userData.skipOverrideMaterial = true;
+
+        //DOM element for this tractogram's controls, built once _build has
+        //run (see _buildElement); appended under #tracts by
+        //Viewer.addTracts. References to the individual inputs are kept so
+        //_syncControls can update them after a programmatic state change
+        //(e.g. a Python call through the JSProxy).
+        this.element = null;
+        this._visibleCheckbox = null;
+        this._opacitySlider = null;
+        this._opacityBox = null;
+        this._groupCheckboxes = {};
+
+        var buffers = {}, names = ["points", "offsets", "colors", "groups"];
+        var pending = names.length;
+        var failed = false;
+        var ondone = function(bufname) {
+            return function(data) {
+                buffers[bufname] = data;
+                if (--pending === 0 && !failed)
+                    this._build(buffers);
+            }.bind(this);
+        }.bind(this);
+        var onfail = function(status) {
+            if (!failed) {
+                failed = true;
+                this.loaded.reject(status);
+            }
+        }.bind(this);
+
+        for (var i = 0; i < names.length; i++)
+            loadBuffer(meta.urls[names[i]], ondone(names[i]), onfail);
+    };
+
+    //Turn the four raw buffers into a THREE.Line of segments, and set up
+    //per-group visibility (this._groupVisible / this._groupSlices /
+    //this._groupIndices) plus the "groups" dat.gui sub-folder, if any.
+    module.Tractogram.prototype._build = function(buffers) {
+        var points = new Float32Array(buffers.points);
+        var offsets = new Uint32Array(buffers.offsets);
+        var rawcolors = new Uint8Array(buffers.colors);
+
+        var npts = points.length / 3;
+        this.n_points = npts;
+        //The offsets array carries a trailing sentinel equal to npts, so there
+        //is one streamline per pair of consecutive entries.
+        var nstream = Math.max(offsets.length - 1, 0);
+        this.n_streamlines = nstream;
+
+        //r69 always uploads vertex attributes as gl.FLOAT (three.js:20276
+        //hardcodes it in setupVertexAttributes), so the uint8 colors must be
+        //expanded to normalized floats -- normalized uint8 attributes are not
+        //an option in this version.
+        var colors = new Float32Array(rawcolors.length);
+        for (var i = 0; i < rawcolors.length; i++)
+            colors[i] = rawcolors[i] / 255;
+
+        this._rawPoints = points;
+        this._rawOffsets = offsets;
+        this._rawColors = colors;
+
+        this._setupGroups(buffers.groups, nstream);
+        this._updateStreamlineVisibility();
+
+        var alpha = this._opacity;
+        this.material = new THREE.LineBasicMaterial({
+            vertexColors: THREE.VertexColors,
+            transparent: alpha < 1,
+            opacity: alpha,
+            //Always write depth, at every opacity -- see setOpacity for why.
+            depthWrite: true,
+            linewidth: (this.meta.linewidth === undefined) ? 1 : this.meta.linewidth,
+        });
+
+        this._buildLine(this._computeGeometryArrays());
+
+        this._buildElement();
+
+        this.loaded.resolve(this);
+    };
+
+    //Parse the "groups" buffer (uint32 streamline indices, the
+    //concatenation of every group in metadata order -- see
+    //Tractogram.groups_wire in cortex/dataset/tractogram.py) plus
+    //`meta.groups` ({name: [start, stop]}, same order) into
+    //this._groupSlices / this._groupIndices, and append a synthetic
+    //"(ungrouped)" group covering any streamline that is not a member of a
+    //real group. Initializes every group (including the pseudo one) to
+    //visible. A tractogram with no groups at all leaves this._hasGroups
+    //false and group filtering out of the picture entirely.
+    module.Tractogram.prototype._setupGroups = function(groupsBuffer, nstream) {
+        var groupIndices = new Uint32Array(groupsBuffer);
+        var groupSlices = {};
+        //Object key order for non-integer-like string keys follows
+        //insertion order in all JS engines we target, and JSON.parse
+        //preserves the order the metadata was serialized in -- but a group
+        //named e.g. "2" would be reordered numerically by the JS engine;
+        //not handled here (group names are expected to be bundle names).
+        for (var gname in this.meta.groups)
+            groupSlices[gname] = this.meta.groups[gname];
+        var hasGroups = Object.keys(groupSlices).length > 0;
+
+        if (hasGroups) {
+            var inGroup = new Uint8Array(nstream);
+            for (var gi = 0; gi < groupIndices.length; gi++)
+                inGroup[groupIndices[gi]] = 1;
+            var ungrouped = [];
+            for (var s = 0; s < nstream; s++)
+                if (!inGroup[s])
+                    ungrouped.push(s);
+            if (ungrouped.length > 0) {
+                var combined = new Uint32Array(groupIndices.length + ungrouped.length);
+                combined.set(groupIndices, 0);
+                combined.set(ungrouped, groupIndices.length);
+                groupSlices["(ungrouped)"] = [groupIndices.length, combined.length];
+                groupIndices = combined;
+            }
+        }
+
+        this._hasGroups = hasGroups;
+        this._groupIndices = groupIndices;
+        this._groupSlices = groupSlices;
+        this._groupVisible = {};
+        for (var name in groupSlices)
+            this._groupVisible[name] = true;
+    };
+
+    //Recompute this._streamlineVisible (Uint8Array, one entry per
+    //streamline) from this._groupVisible. A streamline is visible iff it is
+    //a member of >=1 visible group (ungrouped streamlines follow the
+    //"(ungrouped)" pseudo-group); with no groups at all, every streamline
+    //is visible.
+    module.Tractogram.prototype._updateStreamlineVisibility = function() {
+        var nstream = this.n_streamlines;
+        var vis = new Uint8Array(nstream);
+        if (!this._hasGroups) {
+            vis.fill(1);
+        } else {
+            for (var name in this._groupSlices) {
+                if (!this._groupVisible[name])
+                    continue;
+                var se = this._groupSlices[name];
+                for (var k = se[0]; k < se[1]; k++)
+                    vis[this._groupIndices[k]] = 1;
+            }
+        }
+        this._streamlineVisible = vis;
+    };
+
+    //Build the position/color/index arrays for the currently-visible
+    //streamlines only, in the shape _buildLine expects. Shared by the first
+    //_build and every subsequent _rebuildGeometry.
+    module.Tractogram.prototype._computeGeometryArrays = function() {
+        var points = this._rawPoints, offsets = this._rawOffsets, colors = this._rawColors;
+        var nstream = this.n_streamlines;
+        var visible = this._streamlineVisible;
+        var npts = points.length / 3;
+
+        //Number of segments among visible streamlines: every streamline of
+        //L points yields L-1 segments.
+        var nseg = 0;
+        for (var s = 0; s < nstream; s++) {
+            if (visible[s])
+                nseg += Math.max(offsets[s+1] - offsets[s] - 1, 0);
+        }
+
+        if (module.supportsUint32Index(this.renderer) || npts <= 65535) {
+            //Uint16 is enough (and universally supported) for small tractograms.
+            var index = (npts <= 65535) ? new Uint16Array(2 * nseg) : new Uint32Array(2 * nseg);
+            var k = 0;
+            for (var s = 0; s < nstream; s++) {
+                if (!visible[s])
+                    continue;
+                for (var j = offsets[s]; j + 1 < offsets[s+1]; j++) {
+                    index[k++] = j;
+                    index[k++] = j + 1;
+                }
+            }
+            //Position/color stay the full (unfiltered) buffers -- only the
+            //index changes with visibility.
+            return {indexed: true, position: points, color: colors, index: index};
+        } else {
+            //Fallback: duplicate the endpoints of every segment so no element
+            //index buffer is needed at all.
+            var pos = new Float32Array(6 * nseg);
+            var col = new Float32Array(6 * nseg);
+            var k = 0;
+            for (var s = 0; s < nstream; s++) {
+                if (!visible[s])
+                    continue;
+                for (var j = offsets[s]; j + 1 < offsets[s+1]; j++) {
+                    for (var d = 0; d < 3; d++) {
+                        pos[6*k + d] = points[3*j + d];
+                        pos[6*k + 3 + d] = points[3*(j+1) + d];
+                        col[6*k + d] = colors[3*j + d];
+                        col[6*k + 3 + d] = colors[3*(j+1) + d];
+                    }
+                    k++;
+                }
+            }
+            return {indexed: false, position: pos, color: col};
+        }
+    };
+
+    //Replace this.geometry/this.line with a fresh geometry built from
+    //`arrays` (as returned by _computeGeometryArrays), disposing the old
+    //ones. this.material is reused across rebuilds (only the geometry
+    //changes), so opacity/depthWrite state carries over unchanged.
+    module.Tractogram.prototype._buildLine = function(arrays) {
+        var geometry = new THREE.BufferGeometry();
+        geometry.addAttribute("position", new THREE.BufferAttribute(arrays.position, 3));
+        geometry.addAttribute("color", new THREE.BufferAttribute(arrays.color, 3));
+        if (arrays.indexed)
+            geometry.addAttribute("index", new THREE.BufferAttribute(arrays.index, 1));
+        geometry.computeBoundingSphere();
+
+        if (this.line !== null)
+            this.object.remove(this.line);
+        if (this.geometry !== null)
+            this.geometry.dispose();
+
+        this.geometry = geometry;
+        this.line = new THREE.Line(geometry, this.material, THREE.LinePieces);
+        this.line.name = "Tractogram:" + this.name + ":lines";
+        this.n_vertices = geometry.attributes.position.array.length / 3;
+        //Segments actually drawn: shrinks when groups are hidden on both
+        //the indexed path (index halves) and the fallback path (vertices
+        //are duplicated per segment). n_vertices only shrinks on the latter.
+        this.n_segments = arrays.indexed
+            ? arrays.index.length / 2
+            : this.n_vertices / 2;
+        this._updateRenderOrder();
+        this.object.add(this.line);
+    };
+
+    //Rebuild the rendered geometry from the current this._streamlineVisible
+    //(called after any change to group visibility) and ask the viewer to
+    //redraw. A no-op before the buffers have loaded.
+    module.Tractogram.prototype._rebuildGeometry = function() {
+        if (this._rawPoints === null)
+            return;
+        this._buildLine(this._computeGeometryArrays());
+        this._syncControls();
+        if (window.viewer !== undefined && window.viewer.schedule !== undefined)
+            window.viewer.schedule();
+    };
+
+    //Build this.element: the DOM controls for this tractogram, appended
+    //under #tracts by Viewer.addTracts once this.loaded resolves. Header
+    //row (visibility checkbox, name, collapse toggle) always present; body
+    //(opacity slider, and a per-group "bundles" section when the
+    //tractogram has groups) can be collapsed. Collapsed by default when
+    //there are more than 8 groups, to keep the panel from taking over the
+    //screen for tractograms with many bundles.
+    module.Tractogram.prototype._buildElement = function() {
+        var names = this.groupNames();
+        var collapsed = this._hasGroups && names.length > 8;
+
+        var el = $("<div class='tract-item'></div>");
+        var header = $("<div class='tract-header'></div>");
+        var toggle = $("<span class='tract-toggle'></span>").text(collapsed ? "▸" : "▾");
+        var visibleCheckbox = $("<input type='checkbox'>");
+        var nameLabel = $("<span class='tract-name'></span>").text(this.name);
+        header.append(visibleCheckbox, toggle, nameLabel);
+
+        var body = $("<div class='tract-body'></div>");
+        if (collapsed)
+            body.hide();
+
+        var opacityRow = $("<div class='tract-opacity-row'></div>");
+        var opacitySlider = $("<input type='range' min='0' max='1' step='0.01'>");
+        var opacityBox = $("<input type='number' class='tract-opacity-value' " +
+                           "min='0' max='1' step='0.01'>");
+        opacityRow.append($("<label>opacity</label>"), opacitySlider, opacityBox);
+        body.append(opacityRow);
+
+        this._groupCheckboxes = {};
+        if (this._hasGroups) {
+            var groupsSection = $("<div class='tract-groups'></div>");
+            var actions = $("<div class='tract-groups-actions'></div>");
+            var allLink = $("<a>all</a>");
+            var noneLink = $("<a>none</a>");
+            actions.append(allLink, noneLink);
+            groupsSection.append(actions);
+
+            for (var i = 0; i < names.length; i++) {
+                (function(tract, gname) {
+                    var slice = tract._groupSlices[gname];
+                    var count = slice[1] - slice[0];
+                    var row = $("<div class='tract-group-row'></div>");
+                    var cb = $("<input type='checkbox'>");
+                    var label = $("<span class='tract-group-name'></span>")
+                        .text(gname + " ")
+                        .append($("<span class='tract-group-count'></span>").text("(" + count + ")"));
+                    row.append(cb, label);
+                    groupsSection.append(row);
+                    tract._groupCheckboxes[gname] = cb;
+
+                    cb.on("change", function() {
+                        tract.setGroupVisible(gname, cb.prop("checked"));
+                    });
+                }(this, names[i]));
+            }
+
+            allLink.on("click", function() { this.showAllGroups(); }.bind(this));
+            noneLink.on("click", function() { this.hideAllGroups(); }.bind(this));
+
+            body.append(groupsSection);
+        }
+
+        el.append(header, body);
+
+        //Clicks/drags inside the panel must not reach the WebGL canvas
+        //handlers underneath (camera rotation, picking, etc).
+        el.on("mousedown click", function(e) { e.stopPropagation(); });
+
+        visibleCheckbox.on("change", function() {
+            this.setVisible(visibleCheckbox.prop("checked"));
+        }.bind(this));
+        opacitySlider.on("input change", function() {
+            this.setOpacity(parseFloat(opacitySlider.val()));
+        }.bind(this));
+        //The box takes typed values, so it only commits on change/Enter --
+        //reacting to "input" would fight the user mid-keystroke ("0.0" while
+        //they are on their way to "0.05"). A value outside 0-1 or an empty
+        //box is clamped or ignored by setOpacity, and _syncControls then puts
+        //the accepted value back in the box.
+        opacityBox.on("change", function() {
+            this.setOpacity(opacityBox.val());
+            this._syncControls();
+        }.bind(this));
+        opacityBox.on("keydown", function(e) {
+            if (e.which === 13)
+                opacityBox.trigger("change");
+        });
+        toggle.on("click", function() {
+            collapsed = !collapsed;
+            toggle.text(collapsed ? "▸" : "▾");
+            body.toggle(!collapsed);
+        });
+
+        this.element = el;
+        this._visibleCheckbox = visibleCheckbox;
+        this._opacitySlider = opacitySlider;
+        this._opacityBox = opacityBox;
+
+        this._syncControls();
+    };
+
+    //Keep the DOM controls in step with this tractogram's state, whether it
+    //changed via a click in the panel or programmatically (showAllGroups /
+    //hideAllGroups / setGroupVisible / setVisible / setOpacity called
+    //directly, e.g. from Python through the JSProxy). Called at the end of
+    //every setter.
+    module.Tractogram.prototype._syncControls = function() {
+        if (this._visibleCheckbox !== null)
+            this._visibleCheckbox.prop("checked", this._visible);
+        if (this._opacitySlider !== null)
+            this._opacitySlider.val(this._opacity);
+        if (this._opacityBox !== null)
+            this._opacityBox.val(this._opacity);
+        for (var name in this._groupCheckboxes)
+            this._groupCheckboxes[name].prop("checked", !!this._groupVisible[name]);
+    };
+
+    //Getter/setter pair, in the shape jsplot.Menu expects (called with no
+    //argument it returns the current value, so dat.gui can initialize itself).
+    module.Tractogram.prototype.setVisible = function(value) {
+        if (value === undefined)
+            return this._visible;
+        this._visible = !!value;
+        this._updateVisible();
+        this._syncControls();
+        this._requestRedraw();
+    };
+
+    module.Tractogram.prototype.setOpacity = function(value) {
+        if (value === undefined)
+            return this._opacity;
+        value = parseFloat(value);
+        if (isNaN(value))
+            return;
+        value = Math.min(1, Math.max(0, value));
+        this._opacity = value;
+        if (this.material !== null) {
+            this.material.opacity = value;
+            this.material.transparent = value < 1;
+            //depthWrite stays on at every opacity. Turning it off (the
+            //obvious thing to do for a transparent material) leaves the
+            //streamlines with nothing to depth-test against each other, so
+            //they blend in buffer order instead of depth order: the bundle
+            //that happens to sit last in the geometry paints over the ones
+            //in front of it, and which bundle looks nearest changes the
+            //moment opacity drops below 1. Writing depth keeps the
+            //occlusion identical at every opacity, at the cost of not
+            //seeing one translucent streamline through another -- the
+            //alternative is re-sorting every segment back-to-front on each
+            //camera move, which r69 will not do for us.
+            this.material.depthWrite = true;
+            this.material.needsUpdate = true;
+            this._updateRenderOrder();
+        }
+        this._syncControls();
+        this._requestRedraw();
+    };
+
+    //The panel's inputs are plain DOM controls (not dat.gui, whose menu used
+    //to dispatch an "update" the viewer redraws on), so every state change
+    //has to ask the viewer for a frame itself.
+    module.Tractogram.prototype._requestRedraw = function() {
+        if (window.viewer !== undefined && window.viewer.schedule !== undefined)
+            window.viewer.schedule();
+    };
+
+    //Getter/setter pair for one group's visibility, in the shape jsplot.Menu
+    //expects. Rebuilds the rendered geometry (see _rebuildGeometry).
+    module.Tractogram.prototype.setGroupVisible = function(name, value) {
+        if (value === undefined)
+            return !!this._groupVisible[name];
+        this._groupVisible[name] = !!value;
+        this._updateStreamlineVisibility();
+        this._rebuildGeometry();
+    };
+
+    //Make every group (including "(ungrouped)") visible.
+    module.Tractogram.prototype.showAllGroups = function() {
+        for (var name in this._groupVisible)
+            this._groupVisible[name] = true;
+        this._updateStreamlineVisibility();
+        this._rebuildGeometry();
+    };
+
+    //Hide every group (including "(ungrouped)"): no streamlines render.
+    module.Tractogram.prototype.hideAllGroups = function() {
+        for (var name in this._groupVisible)
+            this._groupVisible[name] = false;
+        this._updateStreamlineVisibility();
+        this._rebuildGeometry();
+    };
+
+    //Names of every group this tractogram knows about, in metadata order,
+    //including the synthetic "(ungrouped)" entry if present. Empty when the
+    //tractogram has no groups.
+    module.Tractogram.prototype.groupNames = function() {
+        return Object.keys(this._groupSlices || {});
+    };
+
+    //Three.js r69 draws opaque objects first, then transparent ones sorted by
+    //their (projected) center depth. Opaque tracts are therefore always
+    //covered by a translucent surface, but as soon as the tracts themselves
+    //become translucent the depth sort can put them *after* the surface --
+    //drawn on top of it, undimmed, so lowering tract opacity from 1 to 0.9
+    //made them brighter. Pinning renderDepth keeps translucent tracts first:
+    //r69 sorts the transparent list ascending by z and then walks it from the
+    //END (renderObjects iterates backwards), so the largest renderDepth is
+    //drawn first, i.e. always under the surface, and the surface's own
+    //opacity attenuates the tracts consistently.
+    module.Tractogram.prototype._updateRenderOrder = function() {
+        if (this.line === null)
+            return;
+        this.line.renderDepth = (this._opacity < 1) ? 1e6 : null;
+    };
+
+    //Streamlines are defined in the fiducial (unmorphed) space, so they only
+    //make sense while the surface is not inflating/flattening.
+    module.Tractogram.prototype.setMix = function(mix) {
+        if (mix === undefined)
+            return this._mix;
+        this._mix = mix;
+        this._updateVisible();
+    };
+
+    module.Tractogram.prototype._updateVisible = function() {
+        this.object.visible = this._visible && this._mix === 0;
+    };
+
+    module.Tractogram.prototype.dispose = function() {
+        if (this.line !== null)
+            this.object.remove(this.line);
+        if (this.geometry !== null)
+            this.geometry.dispose();
+        if (this.material !== null)
+            this.material.dispose();
+        this.geometry = null;
+        this.material = null;
+        this.line = null;
+    };
+
+    return module;
+}(mriview || {}));
diff --git a/cortex/webgl/static.html b/cortex/webgl/static.html
index aed6d5c37..80e08be49 100644
--- a/cortex/webgl/static.html
+++ b/cortex/webgl/static.html
@@ -1,7 +1,7 @@
 {% autoescape None %}
 {% extends template.html %}
 {% block jsinit %}
-    var viewer, subjects, datasets, figure, sock, viewopts;
+    var viewer, subjects, datasets, figure, sock, viewopts, metadata;
 {% end %}
 {% block onload %}
         viewopts = {{viewopts}};
@@ -13,6 +13,8 @@
         figure = new jsplot.W2Figure();
         viewer = figure.add(mriview.Viewer, "main", true);
 
-        dataviews = dataset.fromJSON({{data}});
+        metadata = {{data}};
+        dataviews = dataset.fromJSON(metadata);
         viewer.addData(dataviews);
+        viewer.addTracts(metadata.tracts);
 {% end %}
diff --git a/cortex/webgl/template.html b/cortex/webgl/template.html
index bfabfb158..be0a543b5 100644
--- a/cortex/webgl/template.html
+++ b/cortex/webgl/template.html
@@ -36,6 +36,7 @@
 <script type='text/javascript' src='resources/js/axes3d.js'></script>
 <script type='text/javascript' src='resources/js/mriview_utils.js'></script>
 <script type='text/javascript' src='resources/js/mriview_surface.js'></script>
+<script type='text/javascript' src='resources/js/tractogram.js'></script>
 <script type='text/javascript' src='resources/js/mriview.js'></script>
 
 {% if leapmotion %}
@@ -62,6 +63,7 @@
 			</ul>
 		</div>
 	</div>
+	<div id='tracts' class='tracts-panel'></div>
 	<div id='helpmenu' class='helpmenu'>
 	</div>
 	<div id="picked_value">0.0000</div>
diff --git a/cortex/webgl/view.py b/cortex/webgl/view.py
index cb471f4be..24a515a19 100644
--- a/cortex/webgl/view.py
+++ b/cortex/webgl/view.py
@@ -222,7 +222,11 @@ def make_static(
         submap = None
 
     # Process the data
-    metadata = package.metadata(fmt="data/{name}_{frame}.png", submap=submap)
+    metadata = package.metadata(
+        fmt="data/{name}_{frame}.png",
+        tract_fmt="tracts/{name}_{buf}.bin",
+        submap=submap,
+    )
     images = package.images
     # Write out the PNGs
     for name, imgs in images.items():
@@ -231,6 +235,16 @@ def make_static(
             with open(impath.format(name=name, frame=i), "wb") as binfile:
                 binfile.write(img)
 
+    # Write out the raw streamline buffers of any tractogram
+    if package.tracts:
+        tractpath = os.path.join(outpath, "tracts")
+        os.makedirs(tractpath, exist_ok=True)
+        for name, bufs in package.tracts.items():
+            for buf, contents in bufs.items():
+                fname = os.path.join(tractpath, "%s_%s.bin" % (name, buf))
+                with open(fname, "wb") as binfile:
+                    binfile.write(contents)
+
     # Copy any stimulus files
     stimpath = os.path.join(outpath, "stim")
     for name, view in data:
@@ -438,6 +452,8 @@ def show(
     # is serialized to JSON on demand, when the mixer page is generated.
     metadata = package.metadata()
     images = package.images
+    # Raw streamline buffers, served by TractHandler below.
+    tracts = package.tracts
     subjects = list(package.subjects)
 
     ctmargs = dict(method='mg2', level=9, recache=recache,
@@ -537,6 +553,47 @@ def get(self, path: str):
                 self.set_status(404)
                 self.write_error(404)
 
+    class TractHandler(web.RequestHandler):
+        """Serve the raw streamline buffers of a Tractogram.
+
+        Mirrors DataHandler, for the "/tract/{name}/{buf}/" urls generated by
+        `cortex.webgl.data.Package.tract_names`. `buf` is one of "points"
+        (float32 N x 3), "offsets" (uint32 M + 1), "colors" (uint8 N x 3) or
+        "groups" (uint32, concatenated group streamline indices).
+        """
+        def get(self, path: str):
+            path = path.strip("/")
+            try:
+                tractname, buf = path.rsplit('/', 1)
+            except ValueError:
+                self.set_status(404)
+                self.write_error(404)
+                return
+
+            if tractname in tracts and buf in tracts[tractname]:
+                contents = tracts[tractname][buf]
+                self.set_header("Content-Type", "application/octet-stream")
+
+                if 'Range' in self.request.headers:
+                    self.set_status(206)
+                    rangestr = self.request.headers['Range'].split('=')[1]
+                    start, end = [ int(i) if len(i) > 0 else None for i in rangestr.split('-') ]
+                    # "bytes=100-" means "from 100 to the end" (inclusive end)
+                    if start is None:
+                        start = 0
+                    if end is None or end >= len(contents):
+                        end = len(contents) - 1
+
+                    clenheader = 'bytes %s-%s/%s' % (start, end, len(contents))
+                    self.set_header('Content-Range', clenheader)
+                    self.set_header('Content-Length', end-start+1)
+                    self.write(contents[start:end+1])
+                else:
+                    self.write(contents)
+            else:
+                self.set_status(404)
+                self.write_error(404)
+
     class StimHandler(web.StaticFileHandler):
         def initialize(self):
             pass
@@ -757,7 +814,10 @@ def addData(self, **kwargs):
             Proxy = serve.JSProxy(self.send, "window.viewer.addData")
 
             new_data = dataset.Dataset(**kwargs)
-            new_package = Package(new_data)
+            # require_brains=False: the viewer is already up, so pushing only
+            # a Tractogram is fine (the javascript side just adds it to the
+            # scene and keeps the currently displayed dataview).
+            new_package = Package(new_data, require_brains=False)
             unknown = set(new_package.subjects) - set(subjects)
             if len(unknown) > 0:
                 raise ValueError(
@@ -782,6 +842,11 @@ def addData(self, **kwargs):
             metadata["data"].update(new_metadata["data"])
             metadata["images"].update(new_metadata["images"])
 
+            # Serve the streamline buffers of any newly added tractogram, and
+            # remember them so that a page reload still shows them.
+            tracts.update(new_package.tracts)
+            metadata["tracts"].update(new_metadata["tracts"])
+
             # Forget the brains that no dataview refers to anymore, so that
             # repeatedly refreshing the same dataview does not pile up unused
             # image buffers in the server.
@@ -1052,6 +1117,7 @@ def get_local_client(self):
 
     server = WebApp([(r'/ctm/(.*)', CTMHandler),
                      (r'/data/(.*)', DataHandler),
+                     (r'/tract/(.*)', TractHandler),
                      (r'/stim/(.*)', StimHandler),
                      (r'/mixer.html', MixerHandler),
                      (r'/picker', PickerHandler),
diff --git a/docs/dataset.rst b/docs/dataset.rst
index 64f6a30d1..0e9482149 100644
--- a/docs/dataset.rst
+++ b/docs/dataset.rst
@@ -125,6 +125,8 @@ or from a plain list of ``(L_i, 3)`` streamline arrays::
 
 ``groups`` holds named subsets of streamlines (as arrays of streamline indices, e.g. bundle names); groups may overlap, and a streamline may belong to no group. :meth:`Tractogram.get_group` and :meth:`Tractogram.select` return new tractograms restricted to a subset, and :meth:`Tractogram.subsample` decimates a large tractogram for faster interactive display.
 
+In the WebGL viewer, tractogram controls live in their own panel under the dataset box, with one entry per tractogram (a visibility checkbox, name, and collapse toggle). A tractogram with at least one group gets, inside its (optionally collapsed) entry, an opacity slider and a "bundles" section with "all"/"none" links plus one checkbox per group, in the order groups were given, each labeled with its streamline count; any streamline in no group is covered by an additional ``(ungrouped)`` checkbox. A streamline renders while it belongs to at least one checked group. From Python, toggle a group directly on the live viewer handle, e.g. ``handle.tracts.af.setGroupVisible("CST_L", False)``.
+
 .. note::
    `points` must be expressed in the same mm space as the subject's fiducial surfaces (FreeSurfer scanner RAS mm). Tractography output is often already in this space when the diffusion data was registered to the same T1 used to generate the surfaces; otherwise, pass an `xfm` (4x4 affine) to :meth:`Tractogram.from_trx` to align the streamline positions onto the fiducial surface.
 

From 51a3ccc1986da9614f18a75c994533031eb3a072 Mon Sep 17 00:00:00 2001
From: Matteo Visconti di Oleggio Castello <mvdoc@berkeley.edu>
Date: Sat, 19 Sep 2026 18:41:56 -0700
Subject: [PATCH 2/5] FIX hide a zero-opacity tractogram, and list bundles
 alphabetically

Dragging tract opacity to 0 did not hide the streamlines: it turned them into
silhouettes cut out of the translucent surface. Writing depth at every opacity
is what keeps the bundles from reordering themselves as the slider moves, but
it also means fragments contributing no colour still hide whatever is behind
them. r69's basic shader runs its alphatest discard while gl_FragColor.a is
still just `opacity`, before vertex colours are folded in, so a small constant
alphaTest drops exactly the fragments that would have been invisible anyway,
depth write and all. Being constant, the ALPHATEST define compiles once and
opacity changes stay cheap.

The bundle checkboxes were in wire order, which for a real TRX is arbitrary:
pyAFQ's HCP atlas lists IF0F_R, F_R, F_L, CC_ForcepsMajor and so on. They are
now alphabetical, comparing digit runs as numbers so CST_2 precedes CST_10,
with the synthetic "(ungrouped)" entry pinned last since it is not a bundle
and its leading parenthesis would otherwise float it to the top. groupNames()
returns the same order, so the panel and the API agree.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 cortex/tests/test_webgl_tractogram.py   |  7 +++--
 cortex/webgl/resources/js/tractogram.js | 36 +++++++++++++++++++++----
 docs/dataset.rst                        |  2 +-
 3 files changed, 37 insertions(+), 8 deletions(-)

diff --git a/cortex/tests/test_webgl_tractogram.py b/cortex/tests/test_webgl_tractogram.py
index 466f3962a..b157d4e9b 100644
--- a/cortex/tests/test_webgl_tractogram.py
+++ b/cortex/tests/test_webgl_tractogram.py
@@ -206,11 +206,14 @@ def test_tractogram_renders_in_headless_viewer():
         # return the per-client response list, hence the [0].
         full_n_segments = handle.tracts.af.n_segments
         assert full_n_segments == n - m
-        assert set(handle.tracts.af.groupNames()[0]) == {
+        # Alphabetical, with the synthetic "(ungrouped)" entry last -- not
+        # the order the groups arrived in, which the fixture deliberately
+        # makes the reverse of alphabetical.
+        assert handle.tracts.af.groupNames()[0] == [
             "first_half",
             "second_half",
             "(ungrouped)",
-        }
+        ]
         handle.tracts.af.setGroupVisible("first_half", False)
         shrunk_n_segments = handle.tracts.af.n_segments
         assert 0 < shrunk_n_segments < full_n_segments
diff --git a/cortex/webgl/resources/js/tractogram.js b/cortex/webgl/resources/js/tractogram.js
index 032eb2fe2..f192df6b6 100644
--- a/cortex/webgl/resources/js/tractogram.js
+++ b/cortex/webgl/resources/js/tractogram.js
@@ -1,5 +1,9 @@
 var mriview = (function(module) {
 
+    //Name of the synthetic group covering streamlines that belong to no real
+    //one. Not a bundle, so it is listed after them (see sortGroupNames).
+    var UNGROUPED = "(ungrouped)";
+
     //Fetch a binary payload (one of the tractogram's buffers) as an
     //ArrayBuffer. Same XMLHttpRequest style as surfload.js / CTMLoader.js.
     function loadBuffer(url, callback, errback) {
@@ -177,6 +181,16 @@ var mriview = (function(module) {
             opacity: alpha,
             //Always write depth, at every opacity -- see setOpacity for why.
             depthWrite: true,
+            //...which on its own makes a fully transparent tractogram visible
+            //rather than invisible: fragments that contribute no colour still
+            //write depth, so they hide the translucent surface behind them and
+            //the streamlines show up as silhouettes cut out of the brain.
+            //r69's basic shader runs the alphatest discard while gl_FragColor.a
+            //is still just `opacity` (before vertex colours are folded in), so
+            //a small alphaTest drops exactly the fragments that would have been
+            //invisible anyway, depth write and all. It is a constant, so the
+            //ALPHATEST define is compiled once and opacity changes stay cheap.
+            alphaTest: 0.01,
             linewidth: (this.meta.linewidth === undefined) ? 1 : this.meta.linewidth,
         });
 
@@ -220,7 +234,7 @@ var mriview = (function(module) {
                 var combined = new Uint32Array(groupIndices.length + ungrouped.length);
                 combined.set(groupIndices, 0);
                 combined.set(ungrouped, groupIndices.length);
-                groupSlices["(ungrouped)"] = [groupIndices.length, combined.length];
+                groupSlices[UNGROUPED] = [groupIndices.length, combined.length];
                 groupIndices = combined;
             }
         }
@@ -546,11 +560,23 @@ var mriview = (function(module) {
         this._rebuildGeometry();
     };
 
-    //Names of every group this tractogram knows about, in metadata order,
-    //including the synthetic "(ungrouped)" entry if present. Empty when the
-    //tractogram has no groups.
+    //Alphabetical, case-insensitively and with digit runs compared as
+    //numbers, so CST_2 sorts before CST_10. The synthetic "(ungrouped)" entry
+    //always sorts last: it is not a bundle, and a leading parenthesis would
+    //otherwise float it to the top.
+    module.sortGroupNames = function(names) {
+        return names.slice().sort(function(a, b) {
+            if (a === UNGROUPED) return 1;
+            if (b === UNGROUPED) return -1;
+            return a.localeCompare(b, undefined, {numeric: true, sensitivity: "base"});
+        });
+    };
+
+    //Names of every group this tractogram knows about, alphabetically (see
+    //sortGroupNames), including the synthetic "(ungrouped)" entry if present.
+    //Empty when the tractogram has no groups.
     module.Tractogram.prototype.groupNames = function() {
-        return Object.keys(this._groupSlices || {});
+        return module.sortGroupNames(Object.keys(this._groupSlices || {}));
     };
 
     //Three.js r69 draws opaque objects first, then transparent ones sorted by
diff --git a/docs/dataset.rst b/docs/dataset.rst
index 0e9482149..256982403 100644
--- a/docs/dataset.rst
+++ b/docs/dataset.rst
@@ -125,7 +125,7 @@ or from a plain list of ``(L_i, 3)`` streamline arrays::
 
 ``groups`` holds named subsets of streamlines (as arrays of streamline indices, e.g. bundle names); groups may overlap, and a streamline may belong to no group. :meth:`Tractogram.get_group` and :meth:`Tractogram.select` return new tractograms restricted to a subset, and :meth:`Tractogram.subsample` decimates a large tractogram for faster interactive display.
 
-In the WebGL viewer, tractogram controls live in their own panel under the dataset box, with one entry per tractogram (a visibility checkbox, name, and collapse toggle). A tractogram with at least one group gets, inside its (optionally collapsed) entry, an opacity slider and a "bundles" section with "all"/"none" links plus one checkbox per group, in the order groups were given, each labeled with its streamline count; any streamline in no group is covered by an additional ``(ungrouped)`` checkbox. A streamline renders while it belongs to at least one checked group. From Python, toggle a group directly on the live viewer handle, e.g. ``handle.tracts.af.setGroupVisible("CST_L", False)``.
+In the WebGL viewer, tractogram controls live in their own panel under the dataset box, with one entry per tractogram (a visibility checkbox, name, and collapse toggle). A tractogram with at least one group gets, inside its (optionally collapsed) entry, an opacity slider and a "bundles" section with "all"/"none" links plus one checkbox per group, listed alphabetically rather than in the order they were given, each labeled with its streamline count; any streamline in no group is covered by an additional ``(ungrouped)`` checkbox. A streamline renders while it belongs to at least one checked group. From Python, toggle a group directly on the live viewer handle, e.g. ``handle.tracts.af.setGroupVisible("CST_L", False)``.
 
 .. note::
    `points` must be expressed in the same mm space as the subject's fiducial surfaces (FreeSurfer scanner RAS mm). Tractography output is often already in this space when the diffusion data was registered to the same T1 used to generate the surfaces; otherwise, pass an `xfm` (4x4 affine) to :meth:`Tractogram.from_trx` to align the streamline positions onto the fiducial surface.

From 5d8625ce7583c167beef83385bae453c9c3718df Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 20 Sep 2026 02:42:13 +0000
Subject: [PATCH 3/5] FIX read the served metadata from its assignment, not
 from fromJSON

`_served_metadata` located the dataset payload by the `dataset.fromJSON(`
marker and JSON-decoded from there. Adding the tract panel changed
mixer.html and static.html to assign the payload first, so that
`viewer.addTracts(metadata.tracts)` has something to read:

    metadata = {{data}};
    dataviews = dataset.fromJSON(metadata);

That call now takes an identifier rather than a JSON literal, so the
decode landed on `metadata);` and raised, failing the four tests that read
the served metadata:

    json.decoder.JSONDecodeError: Expecting value: line 15603 column 30

The served page was always correct -- the viewer parses it fine -- so the
marker moves to the assignment. Line 4 of each template declares
`metadata` without an `=`, so the assignment is the page's first
`metadata = `.

Verified against a real served page: a viewer started with
open_browser=False reproduces the failure at exactly the line and column
CI reports, and returns the payload once the marker moves.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015zgY3aPBUWUhHBpisvF6Kw
---
 cortex/tests/test_webgl_headless.py | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/cortex/tests/test_webgl_headless.py b/cortex/tests/test_webgl_headless.py
index 37cde0f1c..d838b9bb4 100644
--- a/cortex/tests/test_webgl_headless.py
+++ b/cortex/tests/test_webgl_headless.py
@@ -742,11 +742,17 @@ def _served_metadata(handle):
     ``show()`` regenerates the page from the same ``metadata`` dict that
     ``addData`` merges into, so this is how we check that a reload of the
     viewer would show everything that has been added so far.
+
+    The payload is the right-hand side of ``mixer.html``'s ``metadata = ...``
+    assignment, not the argument of the ``dataset.fromJSON()`` below it: that
+    call takes the variable, so decoding from there lands on an identifier and
+    raises. Line 4 of the template declares ``metadata`` without an ``=``, so
+    the assignment is the first ``metadata = `` in the page.
     """
     url = "http://localhost:%d/mixer.html" % handle.server.port
     with urllib.request.urlopen(url, timeout=30) as resp:
         page = resp.read().decode("utf-8")
-    marker = "dataset.fromJSON("
+    marker = "metadata = "
     start = page.index(marker) + len(marker)
     return json.JSONDecoder().raw_decode(page, start)[0]
 

From de3b004acdc3a9047f90e6b10cb36110ceceeab0 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 20 Sep 2026 02:14:33 +0000
Subject: [PATCH 4/5] FIX address the review of the tractogram WebGL path

A tractogram's name is a dataset key, i.e. an arbitrary string, and it was
reaching both the buffer urls and the file names of `make_static` verbatim:
`Dataset(**{"../../escape": tract})` wrote outside the output directory, and
any name holding a `/` failed outright. Buffers now travel under a transport
id (`cortex.webgl.data._tract_id`) that is safe as a single url segment and
as a file name; ordinary names pass through unchanged, so the urls stay
readable, and the metadata is still keyed by the name the user gave.

The viewer keys its tractograms by name in a plain object too, where a
tractogram called "constructor" or "toString" looked like one that was
already loaded -- addTracts would "replace" it and rmTracts would then trip
over the inherited value. Every lookup goes through `Viewer.hasTract` now,
and the per-group maps, whose keys are bundle names, are prototype-free.

Streamlines are meaningless against another subject's brain, but in a
multi-subject dataset they stayed on screen when the active dataview (and
with it the surface) switched subjects. A tractogram now shows only while a
dataview of its own subject is active, lines and panel entry alike; and
`Package` refuses at the outset a tractogram whose subject has no dataview
at all, rather than booting a viewer that silently omits it.

Tractograms load outside `viewer.loaded` on purpose, so that a slow
streamline download cannot hold up an otherwise usable viewer -- which left
`getImage`/`save_3d_views` free to screenshot a scene whose streamlines were
still in flight. `headless_viewer` waits for `viewer.tractsState()` on top of
`viewer.loaded`, and reports a failed download rather than waiting it out.

The panel's controls were bare inputs with no accessible name, and the
collapse control was a glyph in a <span>: unreachable by keyboard and
unannounced by a screen reader. They carry their own labels now, the
collapse and all/none controls are real buttons, and each bundle row is a
<label> wrapping its checkbox.

Testing: the index strategy is split into `mriview.indexModeFor`, so the
uint16/uint32/duplicate choice can be checked with plain arguments, and
`forceIndexMode` pins it, so the duplicated-vertex fallback is built and
compared segment by segment against the indexed geometry it replaces instead
of going untested for want of a 65536-point fixture. The headless test drops
its own polling loop, which the new wait makes unnecessary.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011GHv7KSxts6xnv1eQrgouT
---
 cortex/export/headless.py               |  48 ++++++
 cortex/tests/test_webgl_tractogram.py   | 190 ++++++++++++++++++++++--
 cortex/webgl/data.py                    |  91 ++++++++++--
 cortex/webgl/resources/css/mriview.css  |  24 ++-
 cortex/webgl/resources/js/mriview.js    |  74 ++++++++-
 cortex/webgl/resources/js/tractogram.js | 159 +++++++++++++++++---
 cortex/webgl/view.py                    |  26 +++-
 docs/dataset.rst                        |   2 +-
 8 files changed, 551 insertions(+), 63 deletions(-)

diff --git a/cortex/export/headless.py b/cortex/export/headless.py
index 12d2182bc..6ed589e04 100644
--- a/cortex/export/headless.py
+++ b/cortex/export/headless.py
@@ -103,6 +103,50 @@ def _wait_for_viewer_loaded(handle, timeout: float = 60.0) -> None:
     )
 
 
+def _wait_for_tracts_loaded(handle, timeout: float = 60.0) -> None:
+    """Block until every tractogram's buffers have arrived in the browser.
+
+    ``viewer.loaded`` deliberately does not wait for tractograms -- a slow
+    streamline download must not hold up a viewer that is perfectly usable
+    without it (mriview.js: ``addTracts``). That leaves a race for anything
+    that screenshots straight after loading: ``getImage``/``save_3d_views``
+    would catch a scene whose streamlines are still in flight. So poll
+    ``viewer.tractsState()`` too, which answers "resolved" immediately when
+    there are no tractograms at all.
+
+    A failed download is reported rather than waited out: the screenshot
+    would silently be missing streamlines.
+    """
+    deadline = time.monotonic() + timeout
+    poll_interval = 0.1
+    last_err: Optional[str] = None
+    while time.monotonic() < deadline:
+        try:
+            result = handle.send(
+                method="run", params=["window.viewer.tractsState", []]
+            )
+        except Exception as exc:
+            last_err = repr(exc)
+            result = None
+        val = result[0] if isinstance(result, list) and result else result
+        if val == "resolved":
+            return
+        if val == "rejected":
+            raise RuntimeError(
+                "A tractogram's streamline buffers failed to download in the "
+                "headless browser; the viewer would render without them."
+            )
+        if val is not None:
+            last_err = (
+                str(val.get("error", val)) if isinstance(val, dict) else str(val)
+            )
+        time.sleep(poll_interval)
+    raise RuntimeError(
+        f"Tractogram buffers did not finish loading within {timeout:.0f}s "
+        f"(last response: {last_err!r})."
+    )
+
+
 # --------------------------------------------------------------------------- #
 # Helper: run Playwright in a dedicated thread to avoid asyncio conflicts     #
 # --------------------------------------------------------------------------- #
@@ -464,6 +508,10 @@ def _await_client() -> None:
         # calls in tests and callers, and shortens the wait when the
         # browser is faster than the worst-case timeout.
         _wait_for_viewer_loaded(handle, timeout=timeout)
+        # ... and until any tractogram has finished downloading: those load
+        # outside viewer.loaded on purpose, so without this a screenshot
+        # taken right away can come back without its streamlines.
+        _wait_for_tracts_loaded(handle, timeout=timeout)
 
         yield handle
 
diff --git a/cortex/tests/test_webgl_tractogram.py b/cortex/tests/test_webgl_tractogram.py
index b157d4e9b..a47d3f5f0 100644
--- a/cortex/tests/test_webgl_tractogram.py
+++ b/cortex/tests/test_webgl_tractogram.py
@@ -6,12 +6,13 @@
 """
 
 import os
+import re
 
 import numpy as np
 import pytest
 
 import cortex
-from cortex.webgl.data import Package
+from cortex.webgl.data import Package, _tract_id
 
 from .testing_utils import has_playwright
 from .test_tractogram import _make_tractogram, _overlapping_groups
@@ -86,6 +87,55 @@ def test_package_tract_metadata_and_buffers():
         pos += len(idx)
 
 
+def test_tract_id_is_url_and_path_safe():
+    # Ordinary names travel unchanged, so urls and file names stay readable.
+    assert _tract_id("af") == "af"
+    assert _tract_id("AF_left-1") == "AF_left-1"
+
+    # Anything else is slugified: a dataset key is an arbitrary string, and
+    # both the "/tract/{id}/{buf}/" urls and the "tracts/{id}_{buf}.bin"
+    # files would otherwise take a "/" or a ".." literally.
+    for name in ["../escape", "a/b", "tract name", "#frag?q", ".."]:
+        ident = _tract_id(name)
+        assert re.match(r"^[A-Za-z0-9_-]+$", ident), ident
+        assert ident == _tract_id(name), "ids must be deterministic"
+
+    # Names that slugify alike stay distinct.
+    assert _tract_id("a/b") != _tract_id("a b")
+    # ... and a very long key cannot produce an unopenable file name.
+    assert len(_tract_id("x" * 500)) <= 64
+
+
+def test_package_tract_ids_used_in_urls():
+    tract = _make_tractogram(n_streamlines=4, n_points=10)
+    name = "../escape"
+    pkg = Package(cortex.Dataset(**{name: tract}), require_brains=False)
+
+    ident = pkg.tract_ids[name]
+    assert ".." not in ident and "/" not in ident
+    # The metadata is still keyed by the name the user gave; only the
+    # transport urls use the id.
+    urls = pkg.metadata()["tracts"][name]["urls"]
+    assert urls["points"] == "/tract/%s/points/" % ident
+
+
+def test_make_static_sanitizes_tract_names(tmp_path):
+    # A dataset key is an arbitrary string, and it used to be spliced
+    # straight into the buffer file names: "../../escape" would have written
+    # two directories up from `outpath`.
+    tract = _make_tractogram(n_streamlines=4, n_points=10)
+    ds = cortex.Dataset(**{"overlay": _vertex(), "../../escape": tract})
+    outpath = tmp_path / "static"
+    cortex.webgl.make_static(str(outpath), ds, recache=False)
+
+    written = sorted(os.listdir(str(outpath / "tracts")))
+    assert len(written) == 4
+    for fname in written:
+        assert ".." not in fname
+    # Nothing landed next to (rather than inside) the output directory.
+    assert sorted(os.listdir(str(tmp_path))) == ["static"]
+
+
 def test_package_empty_groups_gives_empty_buffer():
     tract = _make_tractogram(n_streamlines=4, n_points=10, groups={})
     pkg = Package(cortex.Dataset(af=tract), require_brains=False)
@@ -132,6 +182,22 @@ def test_package_tractogram_only_raises():
     assert "af" in pkg.tracts
 
 
+def test_package_tract_without_a_dataview_of_its_subject_raises():
+    # A tractogram is only drawn while a dataview of its own subject is
+    # active, so one whose subject has no dataview at all would never show.
+    tract = _make_tractogram(n_streamlines=4, n_points=10)
+    tract.subject = "someone_else"
+    with pytest.raises(ValueError, match="someone_else"):
+        Package(cortex.Dataset(overlay=_vertex(), af=tract))
+
+    # Not the boot path's problem when the viewer is already up, though: the
+    # caller there gets the "unknown subject" check in JSMixer.addData.
+    pkg = Package(
+        cortex.Dataset(overlay=_vertex(), af=tract), require_brains=False
+    )
+    assert pkg.tract_meta["af"]["subject"] == "someone_else"
+
+
 # ---------------------------------------------------------------------------
 # make_static
 # ---------------------------------------------------------------------------
@@ -175,20 +241,15 @@ def test_tractogram_renders_in_headless_viewer():
         # `handle` is a JSProxy rooted at window.viewer: attribute access
         # queries the live javascript object graph over the websocket.
         # The tracts load asynchronously and deliberately do not block
-        # viewer.loaded, so poll until the geometry has been built
-        # (Tractogram.n_points stays 0 until then).
-        import time
-
-        deadline = time.monotonic() + 30
-        n_points = 0
-        while time.monotonic() < deadline:
-            n_points = handle.tracts.af.n_points
-            if n_points:
-                break
-            time.sleep(0.2)
+        # viewer.loaded, but headless_viewer waits for viewer.tractsState()
+        # on top of it -- so the geometry is already built here, with no
+        # polling of our own (Tractogram.n_points stays 0 until then).
+        assert handle.send(
+            method="run", params=["window.viewer.tractsState", []]
+        ) == ["resolved"]
 
         n, m = tract.n_points, tract.n_streamlines
-        assert n_points == n
+        assert handle.tracts.af.n_points == n
         assert handle.tracts.af.n_streamlines == m
         assert handle.tracts.af.object.visible is True
         # Controls now live in a dedicated DOM panel (#tracts) instead of a
@@ -240,3 +301,106 @@ def test_tractogram_renders_in_headless_viewer():
         assert handle.tracts.af.setOpacity()[0] == 1
         handle.tracts.af.setOpacity("")
         assert handle.tracts.af.setOpacity()[0] == 1
+
+        # A tractogram belongs to one subject's scanner space, so it steps
+        # aside (lines and panel entry both) while another subject's dataview
+        # is the active one -- there is only one subject in the test
+        # filestore, so move the tractogram to a fictitious one instead of
+        # building a two-subject dataset.
+        handle.send(
+            method="set",
+            params=["window.viewer.tracts.af.meta.subject", "not_" + subj],
+        )
+        handle.send(method="run", params=["window.viewer._updateTractSubjects", []])
+        assert handle.tracts.af.object.visible is False
+        assert handle.tracts.af.setSubjectShown()[0] is False
+        handle.send(
+            method="set", params=["window.viewer.tracts.af.meta.subject", subj]
+        )
+        handle.send(method="run", params=["window.viewer._updateTractSubjects", []])
+        assert handle.tracts.af.object.visible is True
+
+
+@pytest.mark.skipif(
+    not has_playwright, reason="playwright + Chromium not available"
+)
+def test_tractogram_index_modes_in_headless_viewer():
+    """The three element-index strategies, and the fallback's geometry.
+
+    Which one a geometry gets depends on its size and on whether the GL
+    context has OES_element_index_uint, so a small tractogram in one browser
+    only ever exercises one of them. `mriview.indexModeFor` is the choice on
+    its own (checkable with plain arguments), and `forceIndexMode` pins it,
+    so the duplicated-vertex fallback can be built and compared against the
+    indexed geometry it replaces without uploading 65536+ points.
+    """
+    ds, tract = _dataset()
+    n, m = tract.n_points, tract.n_streamlines
+
+    def run(func, *args):
+        return handle.send(method="run", params=[func, list(args)])[0]
+
+    with cortex.export.headless_viewer(ds, viewer_params={}) as handle:
+        # Small geometries stay on uint16 whatever the extension says; above
+        # 65535 vertices the extension decides between a 32-bit index and
+        # duplicating the endpoints of every segment.
+        assert run("window.mriview.indexModeFor", 100, True) == "uint16"
+        assert run("window.mriview.indexModeFor", 100, False) == "uint16"
+        assert run("window.mriview.indexModeFor", 65535, False) == "uint16"
+        assert run("window.mriview.indexModeFor", 65536, True) == "uint32"
+        assert run("window.mriview.indexModeFor", 65536, False) == "duplicate"
+
+        af = handle.tracts.af
+        assert af.indexType == "uint16"
+        indexed_segments = af.n_segments
+        assert indexed_segments == n - m
+        assert af.n_vertices == n
+        # Endpoints and colors of a segment, as they reach the GPU.
+        indexed = run("window.viewer.tracts.af.segment", 3)
+
+        # Same geometry without an element index: the endpoints of every
+        # segment are duplicated instead, so the vertex count doubles per
+        # segment while the drawn segments -- and their positions and
+        # colors -- must come out identical.
+        handle.send(
+            method="set",
+            params=["window.viewer.tracts.af.forceIndexMode", "duplicate"],
+        )
+        handle.tracts.af._rebuildGeometry()
+        assert handle.tracts.af.indexType == "duplicate"
+        assert handle.tracts.af.n_segments == indexed_segments
+        assert handle.tracts.af.n_vertices == 2 * indexed_segments
+        assert run("window.viewer.tracts.af.segment", 3) == indexed
+
+        # ... and back, so the fallback is not left pinned on the viewer.
+        handle.send(
+            method="set",
+            params=["window.viewer.tracts.af.forceIndexMode", None],
+        )
+        handle.tracts.af._rebuildGeometry()
+        assert handle.tracts.af.indexType == "uint16"
+        assert handle.tracts.af.n_vertices == n
+
+
+@pytest.mark.skipif(
+    not has_playwright, reason="playwright + Chromium not available"
+)
+def test_tractogram_named_like_an_object_prototype_member():
+    """A dataset key is an arbitrary string, including "constructor".
+
+    The viewer keys its tractograms by name in a plain object, so a name that
+    collides with an inherited Object.prototype member used to look like a
+    tractogram that was already loaded -- addTracts would then "replace" it
+    and rmTracts would trip over the inherited value.
+    """
+    tract = _make_tractogram(n_streamlines=4, n_points=10)
+    ds = cortex.Dataset(overlay=_vertex(), constructor=tract)
+
+    with cortex.export.headless_viewer(ds, viewer_params={}) as handle:
+        assert handle.send(
+            method="run", params=["window.viewer.hasTract", ["constructor"]]
+        ) == [True]
+        assert handle.send(
+            method="run", params=["window.viewer.hasTract", ["toString"]]
+        ) == [False]
+        assert handle.tracts.constructor.n_points == tract.n_points
diff --git a/cortex/webgl/data.py b/cortex/webgl/data.py
index 66e70412b..567c614e8 100644
--- a/cortex/webgl/data.py
+++ b/cortex/webgl/data.py
@@ -6,7 +6,8 @@
     data  = dict(__braindata_name=dict(subject=subject, min=min, max=max)),
     images=(__braindata_name=["img1.png", "img2.png"]),
     tracts = dict(name=dict(subject=subject, n_points=N, n_streamlines=M, ...,
-                            urls=dict(points=url, offsets=url, colors=url))),
+                            urls=dict(points=url, offsets=url, colors=url,
+                                      groups=url))),
 )
 
 Tractograms (`cortex.Tractogram`) are handled separately from the BrainData
@@ -19,10 +20,18 @@
 ``[start, stop]`` slice bounds into this buffer rather than counts) -- which
 the viewer fetches and turns into a THREE.js line geometry
 (``resources/js/tractogram.js``).
+
+The urls of those buffers (and the file names `make_static` writes them to)
+are built from a *transport id* rather than from the tractogram's name: a
+name is a dataset key, which may hold anything at all -- including a ``/``
+or a ``..`` that would otherwise escape the output directory (see
+`_tract_id`).
 """
 
+import hashlib
 import os
 import json
+import re
 from io import BytesIO
 import numpy as np
 
@@ -30,6 +39,37 @@
 from .. import volume
 
 
+#: Characters allowed verbatim in a tractogram transport id: safe both as a
+#: single url path segment and as a file name on every platform.
+_TRACT_ID_UNSAFE = re.compile(r"[^A-Za-z0-9_-]")
+
+#: Longest slug kept before falling back to the hashed form, so that a very
+#: long dataset key cannot produce an unopenable file name.
+_TRACT_ID_MAXLEN = 48
+
+
+def _tract_id(name: str) -> str:
+    """A url- and filesystem-safe transport id for a tractogram name.
+
+    Tractogram names are dataset keys, so they are arbitrary strings:
+    ``Dataset(**{"../escape": tract})`` is perfectly legal, and both the
+    ``/tract/{name}/{buf}/`` urls and the ``tracts/{name}_{buf}.bin`` files
+    written by `make_static` would take it literally. Ordinary names
+    (letters, digits, ``_`` and ``-``) are returned unchanged so the urls
+    and file names stay readable; anything else is slugified and
+    disambiguated with a digest of the original name, which keeps the
+    mapping deterministic and collision-free across separate `Package`
+    instances (`cortex.webgl.show` serves tractograms pushed later by
+    `addData` from the same table).
+    """
+    slug = _TRACT_ID_UNSAFE.sub("_", name).strip("_")
+    if slug == name and len(slug) <= _TRACT_ID_MAXLEN:
+        return slug
+    digest = hashlib.sha1(name.encode("utf-8")).hexdigest()[:8]
+    slug = slug[:_TRACT_ID_MAXLEN]
+    return "%s-%s" % (slug, digest) if slug else "tract-%s" % digest
+
+
 # TODO: How to package multiviews?
 class Package(object):
     """Package the data into a form usable by javascript
@@ -62,6 +102,9 @@ def __init__(self, data, require_brains=True):
         # expects views/data/images to hold colormapped brain data only.
         self.tracts = dict()
         self.tract_meta = dict()
+        #: tractogram name -> the url/file-name-safe id its buffers are
+        #: served under (see `_tract_id`).
+        self.tract_ids = dict()
         brain_views = []
         for name, view in items:
             if isinstance(view, dataset.Tractogram):
@@ -80,6 +123,7 @@ def __init__(self, data, require_brains=True):
                     groups=group_indices.astype("<u4").tobytes(),
                 )
                 self.tract_meta[tname] = view.to_json()
+                self.tract_ids[tname] = _tract_id(tname)
             else:
                 brain_views.append(view)
 
@@ -144,13 +188,31 @@ def __init__(self, data, require_brains=True):
                 self.brains[name]["mosaic"] = self.images[name][0][1]
                 self.images[name] = [_pack_png(m) for m, shape in self.images[name]]
 
-        if require_brains and self.tracts and not self.brains:
-            raise ValueError(
-                "A Tractogram cannot be displayed on its own: the webgl "
-                "viewer needs at least one Volume or Vertex dataview to "
-                "build the surfaces and boot. Pass them together, e.g. "
-                "cortex.webshow(cortex.Dataset(curvature=vertex, af=tract))."
+        if require_brains and self.tracts:
+            if not self.brains:
+                raise ValueError(
+                    "A Tractogram cannot be displayed on its own: the webgl "
+                    "viewer needs at least one Volume or Vertex dataview to "
+                    "build the surfaces and boot. Pass them together, e.g. "
+                    "cortex.webshow(cortex.Dataset(curvature=vertex, af=tract))."
+                )
+            # Streamlines are drawn against their own subject's surface only
+            # (mriview.js: Viewer._updateTractSubjects), so a tractogram whose
+            # subject has no dataview of its own would simply never appear.
+            # Say so here rather than opening a viewer that silently omits it.
+            brain_subjects = set(brain.subject for brain in self.uniques)
+            orphans = sorted(
+                set(meta["subject"] for meta in self.tract_meta.values())
+                - brain_subjects
             )
+            if orphans:
+                raise ValueError(
+                    "No Volume or Vertex dataview for tractogram subject(s) "
+                    "%s: the viewer only draws a tractogram while a dataview "
+                    "of its own subject is active, so these streamlines would "
+                    "never be visible. Add a dataview for them, or drop the "
+                    "tractogram." % ", ".join(repr(s) for s in orphans)
+                )
 
     @property
     def views(self):
@@ -205,9 +267,9 @@ def metadata(self, submap=None, tract_fmt="/tract/{name}/{buf}/", **kwargs):
             anonymizing).
         tract_fmt : str
             Format string for the tractogram buffer urls, with ``{name}``
-            (tractogram name) and ``{buf}`` (one of points/offsets/colors)
-            fields. Defaults to the live-server route served by
-            `cortex.webgl.view.TractHandler`.
+            (the tractogram's transport id, see `_tract_id`) and ``{buf}``
+            (one of points/offsets/colors/groups) fields. Defaults to the
+            live-server route served by `cortex.webgl.view.TractHandler`.
         kwargs
             Passed to `image_names` (i.e. its ``fmt``).
         """
@@ -234,11 +296,16 @@ def image_names(self, fmt="/data/{name}/{frame}/"):
         return names
 
     def tract_names(self, fmt="/tract/{name}/{buf}/"):
-        """Urls of the binary buffers of every tractogram, keyed by name."""
+        """Urls of the binary buffers of every tractogram, keyed by name.
+
+        ``{name}`` is filled with the tractogram's transport id, not with
+        its (arbitrary) dataset key -- see `_tract_id`.
+        """
         names = dict()
         for name, bufs in self.tracts.items():
+            ident = self.tract_ids[name]
             names[name] = dict(
-                (buf, fmt.format(name=name, buf=buf)) for buf in sorted(bufs)
+                (buf, fmt.format(name=ident, buf=buf)) for buf in sorted(bufs)
             )
         return names
 
diff --git a/cortex/webgl/resources/css/mriview.css b/cortex/webgl/resources/css/mriview.css
index a19cfba7b..72f0d4cf6 100644
--- a/cortex/webgl/resources/css/mriview.css
+++ b/cortex/webgl/resources/css/mriview.css
@@ -157,6 +157,8 @@ a:visited { color:white; }
     align-items:center;
     cursor:default;
 }
+/* A real <button> (focusable, keyboard-operable), stripped back to the
+   plain glyph it used to be. */
 .tract-header .tract-toggle {
     cursor:pointer;
     width:1.2em;
@@ -164,6 +166,12 @@ a:visited { color:white; }
     text-align:center;
     user-select:none;
     color:#DDD;
+    background:none;
+    border:none;
+    padding:0;
+    margin:0;
+    font:inherit;
+    line-height:1;
 }
 .tract-header .tract-name {
     font-weight:bold;
@@ -183,7 +191,7 @@ a:visited { color:white; }
     align-items:center;
     margin-bottom:4px;
 }
-.tract-opacity-row label {
+.tract-opacity-row .tract-opacity-label {
     margin-right:6px;
     color:#CCC;
 }
@@ -204,13 +212,25 @@ a:visited { color:white; }
 .tract-groups-actions {
     margin-bottom:2px;
 }
-.tract-groups-actions a {
+.tract-groups-actions .tract-groups-title {
+    color:#CCC;
+    margin-right:8px;
+}
+/* Buttons rather than links: they act on the scene, not on a url, and they
+   have to be reachable by keyboard. */
+.tract-groups-actions button.tract-link {
     color:#9CF;
     cursor:pointer;
     text-decoration:underline;
     margin-right:8px;
+    background:none;
+    border:none;
+    padding:0;
+    font:inherit;
 }
 .tract-group-row {
+    display:block;
+    cursor:pointer;
     white-space:nowrap;
     overflow:hidden;
     text-overflow:ellipsis;
diff --git a/cortex/webgl/resources/js/mriview.js b/cortex/webgl/resources/js/mriview.js
index 88512e5d0..0efe989c1 100644
--- a/cortex/webgl/resources/js/mriview.js
+++ b/cortex/webgl/resources/js/mriview.js
@@ -67,7 +67,8 @@ var mriview = (function(module) {
             //the morph (unfold slider, python _set_view, Viewer.setMix)
             //ends up dispatching this event.
             for (var name in this.tracts)
-                this.tracts[name].setMix(evt.mix);
+                if (this.hasTract(name))
+                    this.tracts[name].setMix(evt.mix);
         }.bind(this);
 
         //allowTilt function to attach to surface when it's added
@@ -727,6 +728,7 @@ var mriview = (function(module) {
                 $("#dataopts").show();
             }
             this.fitDataname();
+            this._updateTractSubjects();
             this._updateTractsPanel();
             this.schedule();
             this.loaded.resolve();
@@ -771,7 +773,13 @@ var mriview = (function(module) {
             return;
 
         for (var name in meta) {
-            if (this.tracts[name] !== undefined)
+            if (!Object.prototype.hasOwnProperty.call(meta, name))
+                continue;
+            //Tractogram names are dataset keys, so they may well be
+            //"constructor" or "toString": every lookup in this.tracts goes
+            //through hasOwnProperty, or an inherited Object.prototype member
+            //would pass for a tractogram already on screen.
+            if (this.hasTract(name))
                 this.rmTracts(name);
 
             var tract = new module.Tractogram(name, meta[name], this.renderer);
@@ -781,6 +789,9 @@ var mriview = (function(module) {
             //deliberately does not wait for them, so redraw when they land.
             tract.loaded.done(function(tract) {
                 $(this.object).find("#tracts").append(tract.element);
+                //The element is built only once the buffers land, so the
+                //subject gate has to be reapplied to it here.
+                this._updateTractSubjects();
                 this._updateTractsPanel();
                 this.schedule();
             }.bind(this));
@@ -788,13 +799,61 @@ var mriview = (function(module) {
             if (tract.setMix !== undefined && this.surfs.length > 0)
                 tract.setMix(this.setMix());
         }
+        this._updateTractSubjects();
         this.schedule();
     };
 
+    //Whether `name` is a tractogram this viewer holds. Never `in` or a plain
+    //`!== undefined`: see the comment in addTracts.
+    module.Viewer.prototype.hasTract = function(name) {
+        return Object.prototype.hasOwnProperty.call(this.tracts, name);
+    };
+
+    //Have every tractogram's buffers arrived? "resolved" once they all have
+    //(and immediately when there are none), "rejected" if any download failed,
+    //"pending" while any is still in flight. Polled by
+    //cortex/export/headless.py, which must not screenshot a half-loaded
+    //scene; the viewer's own `loaded` Deferred deliberately does not wait
+    //for tracts, so that a slow tractogram cannot hold up the viewer.
+    module.Viewer.prototype.tractsState = function() {
+        var state = "resolved";
+        for (var name in this.tracts) {
+            if (!this.hasTract(name))
+                continue;
+            var s = this.tracts[name].loaded.state();
+            if (s === "rejected")
+                return "rejected";
+            if (s !== "resolved")
+                state = "pending";
+        }
+        return state;
+    };
+
+    //Streamlines live in one subject's scanner space, so a tractogram only
+    //means something while that subject's surface is the one on screen. In a
+    //multi-subject dataset, switching the active dataview swaps the surface:
+    //the tractograms of every other subject have to step aside (see
+    //Tractogram.setSubjectShown).
+    module.Viewer.prototype._updateTractSubjects = function() {
+        var subject = null;
+        if (this.active !== null && this.active !== undefined &&
+            this.active.data !== undefined && this.active.data.length > 0)
+            subject = this.active.data[0].subject;
+        for (var name in this.tracts) {
+            if (!this.hasTract(name))
+                continue;
+            var tract = this.tracts[name];
+            //With no active dataview yet (tracts can arrive first) there is
+            //nothing to contradict, so leave them shown.
+            tract.setSubjectShown(subject === null ||
+                                  tract.meta.subject === subject);
+        }
+    };
+
     module.Viewer.prototype.rmTracts = function(name) {
-        var tract = this.tracts[name];
-        if (tract === undefined)
+        if (!this.hasTract(name))
             return;
+        var tract = this.tracts[name];
         this.root.remove(tract.object);
         if (tract.element !== null)
             tract.element.remove();
@@ -812,7 +871,12 @@ var mriview = (function(module) {
         var panel = $(this.object).find("#tracts");
         if (panel.length === 0)
             return;
-        var hasTracts = Object.keys(this.tracts).length > 0;
+        //Only the entries actually on screen count: a panel holding nothing
+        //but another subject's (hidden) tractograms would be an empty box.
+        var hasTracts = false;
+        for (var name in this.tracts)
+            if (this.hasTract(name) && this.tracts[name].setSubjectShown())
+                hasTracts = true;
         panel.toggle(hasTracts);
         if (!hasTracts)
             return;
diff --git a/cortex/webgl/resources/js/tractogram.js b/cortex/webgl/resources/js/tractogram.js
index f192df6b6..d7995dc7a 100644
--- a/cortex/webgl/resources/js/tractogram.js
+++ b/cortex/webgl/resources/js/tractogram.js
@@ -4,6 +4,9 @@ var mriview = (function(module) {
     //one. Not a bundle, so it is listed after them (see sortGroupNames).
     var UNGROUPED = "(ungrouped)";
 
+    //Source of unique DOM ids, for the aria-controls wiring in _buildElement.
+    module._tractElementId = 0;
+
     //Fetch a binary payload (one of the tractogram's buffers) as an
     //ArrayBuffer. Same XMLHttpRequest style as surfload.js / CTMLoader.js.
     function loadBuffer(url, callback, errback) {
@@ -47,6 +50,21 @@ var mriview = (function(module) {
         }
     };
 
+    //Which element-index strategy a geometry of `npts` vertices needs:
+    //"uint16" (indexed, 16-bit elements), "uint32" (indexed, 32-bit elements)
+    //or "duplicate" (no index buffer at all, the endpoints of every segment
+    //duplicated). Split out from `indexMode` so it can be checked directly,
+    //without a GL context to fake.
+    module.indexModeFor = function(npts, uint32ok) {
+        if (npts <= 65535)
+            return "uint16";
+        return uint32ok ? "uint32" : "duplicate";
+    };
+
+    module.indexMode = function(npts, renderer) {
+        return module.indexModeFor(npts, module.supportsUint32Index(renderer));
+    };
+
     //A bundle of streamlines, rendered as GL_LINES.
     //
     //`meta` is one entry of the `tracts` dict of the metadata package built by
@@ -61,6 +79,9 @@ var mriview = (function(module) {
         this._visible = (meta.visible === undefined) ? true : !!meta.visible;
         this._opacity = (meta.alpha === undefined) ? 1 : meta.alpha;
         this._mix = 0;
+        //Whether this tractogram's subject is the one currently on screen;
+        //maintained by Viewer._updateTractSubjects (see mriview.js).
+        this._subjectShown = true;
 
         this.n_points = 0;
         this.n_streamlines = 0;
@@ -72,6 +93,13 @@ var mriview = (function(module) {
         this.geometry = null;
         this.material = null;
         this.line = null;
+        //"uint16", "uint32" or "duplicate": how the last built geometry
+        //addresses its vertices (see module.indexMode). Set by _buildLine.
+        this.indexType = null;
+        //Set to one of those three strings to override that choice, e.g. to
+        //force the duplicated-vertex fallback on a driver that advertises
+        //OES_element_index_uint but mishandles it. null follows the renderer.
+        this.forceIndexMode = null;
 
         //Per-group visibility (name -> bool), including a synthetic
         //"(ungrouped)" entry when at least one streamline belongs to no
@@ -82,13 +110,16 @@ var mriview = (function(module) {
         //pseudo-group). this._hasGroups records whether group filtering
         //applies at all, so setVisible-only tractograms skip it entirely.
         this._hasGroups = false;
-        this._groupVisible = {};
+        //Group names come from the dataset, so these maps are prototype-free:
+        //a bundle called "__proto__" or "constructor" must be an ordinary key
+        //rather than a reference to (or an overwrite of) Object.prototype.
+        this._groupVisible = Object.create(null);
         //Uint32Array: concatenation of every real group's streamline
         //indices (server "groups" buffer) followed by the synthetic
         //"(ungrouped)" group's indices, if any -- see _build.
         this._groupIndices = null;
         //name -> [start, stop] slice into _groupIndices.
-        this._groupSlices = {};
+        this._groupSlices = Object.create(null);
         //Uint8Array of length n_streamlines, recomputed by
         //_updateStreamlineVisibility whenever _groupVisible changes: 1 if
         //the streamline is a member of >=1 visible group (or, with no
@@ -121,7 +152,7 @@ var mriview = (function(module) {
         this._visibleCheckbox = null;
         this._opacitySlider = null;
         this._opacityBox = null;
-        this._groupCheckboxes = {};
+        this._groupCheckboxes = Object.create(null);
 
         var buffers = {}, names = ["points", "offsets", "colors", "groups"];
         var pending = names.length;
@@ -212,14 +243,18 @@ var mriview = (function(module) {
     //false and group filtering out of the picture entirely.
     module.Tractogram.prototype._setupGroups = function(groupsBuffer, nstream) {
         var groupIndices = new Uint32Array(groupsBuffer);
-        var groupSlices = {};
+        //Prototype-free: group names are dataset-supplied, so "__proto__" has
+        //to land as an ordinary key rather than reset the prototype.
+        var groupSlices = Object.create(null);
         //Object key order for non-integer-like string keys follows
         //insertion order in all JS engines we target, and JSON.parse
         //preserves the order the metadata was serialized in -- but a group
         //named e.g. "2" would be reordered numerically by the JS engine;
         //not handled here (group names are expected to be bundle names).
-        for (var gname in this.meta.groups)
-            groupSlices[gname] = this.meta.groups[gname];
+        var metagroups = this.meta.groups || {};
+        for (var gname in metagroups)
+            if (Object.prototype.hasOwnProperty.call(metagroups, gname))
+                groupSlices[gname] = metagroups[gname];
         var hasGroups = Object.keys(groupSlices).length > 0;
 
         if (hasGroups) {
@@ -242,7 +277,7 @@ var mriview = (function(module) {
         this._hasGroups = hasGroups;
         this._groupIndices = groupIndices;
         this._groupSlices = groupSlices;
-        this._groupVisible = {};
+        this._groupVisible = Object.create(null);
         for (var name in groupSlices)
             this._groupVisible[name] = true;
     };
@@ -286,9 +321,10 @@ var mriview = (function(module) {
                 nseg += Math.max(offsets[s+1] - offsets[s] - 1, 0);
         }
 
-        if (module.supportsUint32Index(this.renderer) || npts <= 65535) {
+        var mode = this.forceIndexMode || module.indexMode(npts, this.renderer);
+        if (mode !== "duplicate") {
             //Uint16 is enough (and universally supported) for small tractograms.
-            var index = (npts <= 65535) ? new Uint16Array(2 * nseg) : new Uint32Array(2 * nseg);
+            var index = (mode === "uint16") ? new Uint16Array(2 * nseg) : new Uint32Array(2 * nseg);
             var k = 0;
             for (var s = 0; s < nstream; s++) {
                 if (!visible[s])
@@ -300,7 +336,7 @@ var mriview = (function(module) {
             }
             //Position/color stay the full (unfiltered) buffers -- only the
             //index changes with visibility.
-            return {indexed: true, position: points, color: colors, index: index};
+            return {mode: mode, indexed: true, position: points, color: colors, index: index};
         } else {
             //Fallback: duplicate the endpoints of every segment so no element
             //index buffer is needed at all.
@@ -320,7 +356,7 @@ var mriview = (function(module) {
                     k++;
                 }
             }
-            return {indexed: false, position: pos, color: col};
+            return {mode: mode, indexed: false, position: pos, color: col};
         }
     };
 
@@ -342,6 +378,7 @@ var mriview = (function(module) {
             this.geometry.dispose();
 
         this.geometry = geometry;
+        this.indexType = arrays.mode;
         this.line = new THREE.Line(geometry, this.material, THREE.LinePieces);
         this.line.name = "Tractogram:" + this.name + ":lines";
         this.n_vertices = geometry.attributes.position.array.length / 3;
@@ -355,6 +392,38 @@ var mriview = (function(module) {
         this.object.add(this.line);
     };
 
+    //Positions and colors of drawn segment `i`, as they reach the GPU:
+    //{position:[x0,y0,z0,x1,y1,z1], color:[r0,g0,b0,r1,g1,b1]} with colors in
+    //0-1. Both geometry paths answer identically, which is what makes the
+    //duplicated-vertex fallback checkable against the indexed geometry (it is
+    //the only way to see the difference from outside, since the two draw the
+    //same picture). Returns null for an out-of-range segment.
+    module.Tractogram.prototype.segment = function(i) {
+        if (this.geometry === null || i < 0 || i >= this.n_segments)
+            return null;
+        var pos = this.geometry.attributes.position.array;
+        var col = this.geometry.attributes.color.array;
+        var index = this.geometry.attributes.index;
+        var a, b;
+        if (index !== undefined) {
+            a = index.array[2*i];
+            b = index.array[2*i + 1];
+        } else {
+            a = 2*i;
+            b = 2*i + 1;
+        }
+        var out = {position: [], color: []}, d;
+        for (d = 0; d < 3; d++) {
+            out.position.push(pos[3*a + d]);
+            out.color.push(col[3*a + d]);
+        }
+        for (d = 0; d < 3; d++) {
+            out.position.push(pos[3*b + d]);
+            out.color.push(col[3*b + d]);
+        }
+        return out;
+    };
+
     //Rebuild the rendered geometry from the current this._streamlineVisible
     //(called after any change to group visibility) and ask the viewer to
     //redraw. A no-op before the buffers have loaded.
@@ -377,31 +446,52 @@ var mriview = (function(module) {
     module.Tractogram.prototype._buildElement = function() {
         var names = this.groupNames();
         var collapsed = this._hasGroups && names.length > 8;
+        //Every control carries its own accessible name: the panel is built
+        //from bare inputs, so nothing else would announce what they act on.
+        //The collapse control is a real <button> for the same reason -- a
+        //<span> holding a glyph is neither focusable nor operable by keyboard.
+        var bodyId = "tract-body-" + (module._tractElementId++);
 
         var el = $("<div class='tract-item'></div>");
         var header = $("<div class='tract-header'></div>");
-        var toggle = $("<span class='tract-toggle'></span>").text(collapsed ? "▸" : "▾");
-        var visibleCheckbox = $("<input type='checkbox'>");
+        var toggle = $("<button type='button' class='tract-toggle'></button>")
+            .text(collapsed ? "▸" : "▾")
+            .attr({"aria-expanded": collapsed ? "false" : "true",
+                   "aria-controls": bodyId,
+                   "aria-label": "settings for " + this.name,
+                   title: "show/hide the settings for " + this.name});
+        var visibleCheckbox = $("<input type='checkbox'>")
+            .attr({"aria-label": "show " + this.name,
+                   title: "show/hide " + this.name});
         var nameLabel = $("<span class='tract-name'></span>").text(this.name);
         header.append(visibleCheckbox, toggle, nameLabel);
 
-        var body = $("<div class='tract-body'></div>");
+        var body = $("<div class='tract-body'></div>").attr("id", bodyId);
         if (collapsed)
             body.hide();
 
         var opacityRow = $("<div class='tract-opacity-row'></div>");
-        var opacitySlider = $("<input type='range' min='0' max='1' step='0.01'>");
+        var opacitySlider = $("<input type='range' min='0' max='1' step='0.01'>")
+            .attr({"aria-label": "opacity of " + this.name,
+                   title: "opacity of " + this.name});
         var opacityBox = $("<input type='number' class='tract-opacity-value' " +
-                           "min='0' max='1' step='0.01'>");
-        opacityRow.append($("<label>opacity</label>"), opacitySlider, opacityBox);
+                           "min='0' max='1' step='0.01'>")
+            .attr({"aria-label": "opacity of " + this.name + ", as a number",
+                   title: "opacity of " + this.name});
+        opacityRow.append($("<span class='tract-opacity-label'>opacity</span>"),
+                          opacitySlider, opacityBox);
         body.append(opacityRow);
 
-        this._groupCheckboxes = {};
+        this._groupCheckboxes = Object.create(null);
         if (this._hasGroups) {
-            var groupsSection = $("<div class='tract-groups'></div>");
+            var groupsSection = $("<div class='tract-groups'></div>")
+                .attr({role: "group", "aria-label": "bundles of " + this.name});
             var actions = $("<div class='tract-groups-actions'></div>");
-            var allLink = $("<a>all</a>");
-            var noneLink = $("<a>none</a>");
+            actions.append($("<span class='tract-groups-title'>bundles</span>"));
+            var allLink = $("<button type='button' class='tract-link'>all</button>")
+                .attr("aria-label", "show every bundle of " + this.name);
+            var noneLink = $("<button type='button' class='tract-link'>none</button>")
+                .attr("aria-label", "hide every bundle of " + this.name);
             actions.append(allLink, noneLink);
             groupsSection.append(actions);
 
@@ -409,7 +499,9 @@ var mriview = (function(module) {
                 (function(tract, gname) {
                     var slice = tract._groupSlices[gname];
                     var count = slice[1] - slice[0];
-                    var row = $("<div class='tract-group-row'></div>");
+                    //A <label> wrapping the checkbox names it for a screen
+                    //reader and makes the whole row a click target.
+                    var row = $("<label class='tract-group-row'></label>");
                     var cb = $("<input type='checkbox'>");
                     var label = $("<span class='tract-group-name'></span>")
                         .text(gname + " ")
@@ -431,6 +523,8 @@ var mriview = (function(module) {
         }
 
         el.append(header, body);
+        if (!this._subjectShown)
+            el.hide();
 
         //Clicks/drags inside the panel must not reach the WebGL canvas
         //handlers underneath (camera rotation, picking, etc).
@@ -458,6 +552,7 @@ var mriview = (function(module) {
         toggle.on("click", function() {
             collapsed = !collapsed;
             toggle.text(collapsed ? "▸" : "▾");
+            toggle.attr("aria-expanded", collapsed ? "false" : "true");
             body.toggle(!collapsed);
         });
 
@@ -539,6 +634,8 @@ var mriview = (function(module) {
     module.Tractogram.prototype.setGroupVisible = function(name, value) {
         if (value === undefined)
             return !!this._groupVisible[name];
+        if (this._groupSlices[name] === undefined)
+            return;
         this._groupVisible[name] = !!value;
         this._updateStreamlineVisibility();
         this._rebuildGeometry();
@@ -604,8 +701,24 @@ var mriview = (function(module) {
         this._updateVisible();
     };
 
+    //Whether this tractogram's subject is the one currently on screen (see
+    //Viewer._updateTractSubjects). A tractogram belongs to one subject's
+    //scanner space, so against another subject's surface its streamlines are
+    //meaningless -- both the lines and the panel entry step aside until that
+    //subject's dataview is active again.
+    module.Tractogram.prototype.setSubjectShown = function(shown) {
+        if (shown === undefined)
+            return this._subjectShown;
+        this._subjectShown = !!shown;
+        this._updateVisible();
+        if (this.element !== null)
+            this.element.toggle(this._subjectShown);
+        this._requestRedraw();
+    };
+
     module.Tractogram.prototype._updateVisible = function() {
-        this.object.visible = this._visible && this._mix === 0;
+        this.object.visible = this._visible && this._mix === 0 &&
+                              this._subjectShown;
     };
 
     module.Tractogram.prototype.dispose = function() {
diff --git a/cortex/webgl/view.py b/cortex/webgl/view.py
index 24a515a19..89fc727f3 100644
--- a/cortex/webgl/view.py
+++ b/cortex/webgl/view.py
@@ -235,13 +235,17 @@ def make_static(
             with open(impath.format(name=name, frame=i), "wb") as binfile:
                 binfile.write(img)
 
-    # Write out the raw streamline buffers of any tractogram
+    # Write out the raw streamline buffers of any tractogram. The file names
+    # use the transport id rather than the dataset key, which is an arbitrary
+    # string -- a key of "../escape" would otherwise write outside `outpath`
+    # (see cortex.webgl.data._tract_id).
     if package.tracts:
         tractpath = os.path.join(outpath, "tracts")
         os.makedirs(tractpath, exist_ok=True)
         for name, bufs in package.tracts.items():
+            ident = package.tract_ids[name]
             for buf, contents in bufs.items():
-                fname = os.path.join(tractpath, "%s_%s.bin" % (name, buf))
+                fname = os.path.join(tractpath, "%s_%s.bin" % (ident, buf))
                 with open(fname, "wb") as binfile:
                     binfile.write(contents)
 
@@ -452,8 +456,12 @@ def show(
     # is serialized to JSON on demand, when the mixer page is generated.
     metadata = package.metadata()
     images = package.images
-    # Raw streamline buffers, served by TractHandler below.
-    tracts = package.tracts
+    # Raw streamline buffers, served by TractHandler below, keyed by the
+    # transport id their urls were built from (not by the dataset key, which
+    # may hold any character at all -- see cortex.webgl.data._tract_id).
+    tracts = dict(
+        (package.tract_ids[name], bufs) for name, bufs in package.tracts.items()
+    )
     subjects = list(package.subjects)
 
     ctmargs = dict(method='mg2', level=9, recache=recache,
@@ -556,8 +564,9 @@ def get(self, path: str):
     class TractHandler(web.RequestHandler):
         """Serve the raw streamline buffers of a Tractogram.
 
-        Mirrors DataHandler, for the "/tract/{name}/{buf}/" urls generated by
-        `cortex.webgl.data.Package.tract_names`. `buf` is one of "points"
+        Mirrors DataHandler, for the "/tract/{id}/{buf}/" urls generated by
+        `cortex.webgl.data.Package.tract_names`, where `id` is a tractogram's
+        transport id (`cortex.webgl.data._tract_id`). `buf` is one of "points"
         (float32 N x 3), "offsets" (uint32 M + 1), "colors" (uint8 N x 3) or
         "groups" (uint32, concatenated group streamline indices).
         """
@@ -844,7 +853,10 @@ def addData(self, **kwargs):
 
             # Serve the streamline buffers of any newly added tractogram, and
             # remember them so that a page reload still shows them.
-            tracts.update(new_package.tracts)
+            tracts.update(
+                (new_package.tract_ids[name], bufs)
+                for name, bufs in new_package.tracts.items()
+            )
             metadata["tracts"].update(new_metadata["tracts"])
 
             # Forget the brains that no dataview refers to anymore, so that
diff --git a/docs/dataset.rst b/docs/dataset.rst
index 256982403..deb42ce36 100644
--- a/docs/dataset.rst
+++ b/docs/dataset.rst
@@ -125,7 +125,7 @@ or from a plain list of ``(L_i, 3)`` streamline arrays::
 
 ``groups`` holds named subsets of streamlines (as arrays of streamline indices, e.g. bundle names); groups may overlap, and a streamline may belong to no group. :meth:`Tractogram.get_group` and :meth:`Tractogram.select` return new tractograms restricted to a subset, and :meth:`Tractogram.subsample` decimates a large tractogram for faster interactive display.
 
-In the WebGL viewer, tractogram controls live in their own panel under the dataset box, with one entry per tractogram (a visibility checkbox, name, and collapse toggle). A tractogram with at least one group gets, inside its (optionally collapsed) entry, an opacity slider and a "bundles" section with "all"/"none" links plus one checkbox per group, listed alphabetically rather than in the order they were given, each labeled with its streamline count; any streamline in no group is covered by an additional ``(ungrouped)`` checkbox. A streamline renders while it belongs to at least one checked group. From Python, toggle a group directly on the live viewer handle, e.g. ``handle.tracts.af.setGroupVisible("CST_L", False)``.
+In the WebGL viewer, tractogram controls live in their own panel under the dataset box, with one entry per tractogram: a visibility checkbox, the name and a collapse toggle in the header, and an opacity slider in the (optionally collapsed) body. A tractogram with at least one group also gets a "bundles" section below that slider, with "all"/"none" buttons plus one checkbox per group, listed alphabetically rather than in the order they were given and each labeled with its streamline count; any streamline in no group is covered by an additional ``(ungrouped)`` checkbox. A streamline renders while it belongs to at least one checked group. In a dataset holding several subjects, a tractogram is shown only while a dataview of its own subject is the active one, since its coordinates mean nothing against another brain. From Python, toggle a group directly on the live viewer handle, e.g. ``handle.tracts.af.setGroupVisible("CST_L", False)``.
 
 .. note::
    `points` must be expressed in the same mm space as the subject's fiducial surfaces (FreeSurfer scanner RAS mm). Tractography output is often already in this space when the diffusion data was registered to the same T1 used to generate the surfaces; otherwise, pass an `xfm` (4x4 affine) to :meth:`Tractogram.from_trx` to align the streamline positions onto the fiducial surface.

From 139e7c94b29b2b58f07d51142e83436333b99f25 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 20 Sep 2026 02:17:50 +0000
Subject: [PATCH 5/5] FIX collapse duplicate BrainData in Package.uniques by
 name

`self.brains` and `self.images` are keyed by a BrainData's name, which is a
hash of its array, so two distinct dataviews holding the same data are one
brain on the wire. They were two entries in `uniques` all the same (BrainData
compares by identity), which had `reorder` rewrite `self.images[name]` a
second time on top of the npy blob its first pass had just written there.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011GHv7KSxts6xnv1eQrgouT
---
 cortex/tests/test_webgl_tractogram.py | 18 ++++++++++++++++++
 cortex/webgl/data.py                  | 13 ++++++++++---
 2 files changed, 28 insertions(+), 3 deletions(-)

diff --git a/cortex/tests/test_webgl_tractogram.py b/cortex/tests/test_webgl_tractogram.py
index a47d3f5f0..0f670c368 100644
--- a/cortex/tests/test_webgl_tractogram.py
+++ b/cortex/tests/test_webgl_tractogram.py
@@ -159,6 +159,24 @@ def test_package_keeps_tracts_out_of_views_and_data():
     assert all(not isinstance(u, cortex.Tractogram) for u in pkg.uniques)
 
 
+def test_package_uniques_are_deduplicated_by_name():
+    # Two dataviews holding the same array are one brain on the wire (they
+    # share a name, which is a hash of the data), so they must appear once in
+    # `uniques`: reorder() rewrites self.images[name] in place, and a second
+    # pass would run over the first pass's output.
+    zeros = np.zeros(cortex.db.get_surf(subj, "fiducial", merge=True)[0].shape[0],
+                     dtype=np.float32)
+    ds = cortex.Dataset(
+        a=cortex.Vertex(zeros.copy(), subj),
+        b=cortex.Vertex(zeros.copy(), subj),
+    )
+    pkg = Package(ds)
+    assert len(pkg.uniques) == 1
+    assert len(pkg.brains) == 1
+    # ... while both dataviews still reach the viewer.
+    assert [view["name"] for view in pkg.views] == ["a", "b"]
+
+
 def test_package_reorder_ignores_tracts():
     tract = _make_tractogram(n_streamlines=8, n_points=15)
     pkg = Package(cortex.Dataset(af=tract), require_brains=False)
diff --git a/cortex/webgl/data.py b/cortex/webgl/data.py
index 567c614e8..21bee2321 100644
--- a/cortex/webgl/data.py
+++ b/cortex/webgl/data.py
@@ -127,12 +127,19 @@ def __init__(self, data, require_brains=True):
             else:
                 brain_views.append(view)
 
-        # Deduplicate while keeping the dataset order (BrainData hashes by
-        # identity, so a plain set would shuffle the brains between runs).
+        # Deduplicate while keeping the dataset order (a plain set would
+        # shuffle the brains between runs). By name rather than by object: a
+        # name is a hash of the array, and self.brains/self.images are keyed
+        # by it, so two distinct BrainData holding the same data are one
+        # brain on the wire -- while as two entries here (BrainData compares
+        # by identity) they would have reorder() rewrite the second one on
+        # top of the first one's output.
         self.uniques = []
+        seen = set()
         for view in brain_views:
             for sv in view.uniques(collapse=True):
-                if sv not in self.uniques:
+                if sv.name not in seen:
+                    seen.add(sv.name)
                     self.uniques.append(sv)
         # Tract subjects count too: `show` builds CTM packs per subject,
         # `addData` rejects unknown subjects and `make_static(anonymize=True)`