Document tractography, with an example and visual references

[mvdoc]

Stack

Merge bottom-up; each PR is based on the one above it.

1. Add a surface_opacity control to the WebGL viewer #740 — Add a surface_opacity control to the WebGL viewer
2. Add a Tractogram dataview for streamlines #741 — Add a Tractogram dataview for streamlines
3. Render Tractogram streamlines in the WebGL viewer #742 — Render Tractogram streamlines in the WebGL viewer
4. Document tractography, with an example and visual references #743 — Document tractography, with an example and visual references

Documentation, a gallery example and visual references for the tractography
feature.

• docs/tractography.rst: loading TRX, the millimetre space the points
  have to be in, the colour modes, the viewer's tract panel, decimating a large
  tractogram, and what the feature cannot do — one-pixel lines, no flatmap, no
  HDF5. Linked from the user guide.
• examples/tractography/plot_tractogram.py: three synthetic bundles on
  S1, rendered headlessly against a translucent cortex in both orientation and
  scalar colouring, so the gallery needs no diffusion data.
• A tracts suite in the visual-regression tests: the same bundles against
  an opaque cortex, a translucent one, and a translucent one with translucent
  streamlines. The third earns its keep — it is what fails if the streamlines
  stop occluding each other, which no tolerance on the other two would catch.
  Checked against the real renderer rather than assumed: reintroducing that
  regression by hand moves 0.7% of the render past the gross-difference
  threshold, against a 0.1% limit.
• save_3d_views accepts a Dataset, since a Tractogram cannot be
  rendered alone and so never arrives as a lone dataview, and
  headless_viewer's annotation follows. A custom list_surfaces dict no
  longer gets stringified into the output filename.
• AGENTS.md notes the container and the streamline transport.

Testing

Three new LFS reference images, generated on the same Chromium and matplotlib
builds as the existing ones. Full suite green.

---

🤖 Generated with Claude Code

[Copilot]

Copilot review overview

🟡 Changes recommended

The decimation examples discard the returned tractogram, and contributor documentation and one type annotation are inaccurate.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1 · 3

Open (4)

• Allow tuple annotations for tract suite view parameters · New
• Correct outdated claim about the minimum CI Python version · New
• Assign subsample result and clarify strategies are alternatives · New
• Discarded subsample result leaves the browser payload unchanged · New

What changed in this PR

Adds tractography documentation, a synthetic gallery example, screenshot support for datasets, and visual regression coverage.

Changes:

• Documents tractogram loading, alignment, coloring, controls, and limitations.
• Extends headless 3D export to accept single-subject datasets.
• Adds three tractography visual regression scenarios.

File	Description
examples/​tractography/​README.txt	Introduces the tractography gallery section.
examples/​tractography/​plot_tractogram.py	Demonstrates synthetic tract rendering and coloring.
docs/​tractography.rst	Adds the tractography user guide.
docs/​index.rst	Links the new guide.
cortex/​tests/​test_webgl_tractogram.py	Tests dataset subject resolution.
cortex/​tests/​test_visual_regression.py	Adds tract rendering regression tests.
cortex/​tests/​reference_images/​tracts/​webgl_tracts_translucent.webp	Adds translucent-surface reference.
cortex/​tests/​reference_images/​tracts/​webgl_tracts_translucent_tracts.webp	Adds translucent-tract reference.
cortex/​tests/​reference_images/​tracts/​webgl_tracts_opaque.webp	Adds opaque-surface reference.
cortex/​tests/​reference_images/​README.md	Documents the new reference suite.
cortex/​export/​save_views.py	Supports datasets and custom surface filenames.
cortex/​export/​headless.py	Updates dataset support annotations.
AGENTS.md	Documents tractogram architecture and transport.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[mvdoc]

run-tests is red on fb2bfbd, but not because of anything in this PR — the failure is inherited from the base branch, and I have a verified fix that belongs there rather than here.

What is failing — four tests, on every Python in the matrix:

FAILED cortex/tests/test_webgl_headless.py::TestAddData::test_updates_served_metadata
FAILED cortex/tests/test_webgl_headless.py::TestAddData::test_replaces_existing_name
FAILED cortex/tests/test_webgl_headless.py::TestAddData::test_rejects_unknown_subject
FAILED cortex/tests/test_webgl_headless.py::test_addData_vertex_data
- json.decoder.JSONDecodeError: Expecting value: line 15603 column 30

Why it is not this PR's. The base branch tractography/3-webgl fails with the same four tests and the same character offsets (run-tests (3.11) on 72c0836, the tip of #742). This PR touches docs, a gallery example, save_3d_views and the visual-regression suite; none of it reaches test_webgl_headless.py. The new tracts visual-regression suite itself passes.

Root cause. c5893a0 ("ENH render Tractogram streamlines in the WebGL viewer") changed mixer.html and static.html from

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

to

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

so that viewer.addTracts(metadata.tracts) has something to read. _served_metadata in cortex/tests/test_webgl_headless.py still locates the payload by the old marker:

marker = "dataset.fromJSON("
start = page.index(marker) + len(marker)
return json.JSONDecoder().raw_decode(page, start)[0]

That call now takes the identifier metadata, not a JSON literal, so raw_decode lands on metadata); and raises. The line number in the error is simply where dataset.fromJSON( now sits — after the ~1.1 MB blob. It is the test helper that is stale, not the served page: the page is correct, and the viewer parses it fine.

Fix (in cortex/tests/test_webgl_headless.py):

-    marker = "dataset.fromJSON("
+    marker = "metadata = "
     start = page.index(marker) + len(marker)
     return json.JSONDecoder().raw_decode(page, start)[0]

metadata = occurs once in the rendered page (line 4 declares it as metadata;, without the =), so page.index finds the assignment. Verified against a real rendered page here — make_static on a Volume, then both markers: the old one raises the same JSONDecodeError: Expecting value, the new one returns the payload with keys ['data', 'images', 'tracts', 'views'].

I have not pushed it, because the breakage is in #742 and the fix should land there so that PR merges green rather than carrying a red test into main until this one lands. Say the word if you would rather have it here.

No re-run: the failure is deterministic, not a flake.

---

Generated by Claude Code

[mvdoc]

Fixed, in #742 rather than here: 3721b2c on tractography/3-webgl moves _served_metadata's marker to the metadata = assignment. This branch now carries it through a merge of the base (e6ac083), so CI here runs against the fix.

Verified before pushing: a viewer started with open_browser=False, then the helper's own parse against the real served mixer.html — the old marker fails at line 15603 column 30, the exact line and column CI reports, and the new one returns the payload with keys ['data', 'images', 'tracts', 'views'].

---

Generated by Claude Code