Pure-python surf2surf matrix (direct nnfr construction)

[mvdoc]

Summary

get_mri_surf2surf_matrix previously reverse-engineered FreeSurfer's mri_surf2surf: it warped the coordinate maps through the binary, probed it with 40 random test images, and solved a per-vertex least-squares problem to recover the sparse transform. That required FreeSurfer installed and called several times.

The mapping FreeSurfer actually computes is just its nnfr (nearest-neighbor, forward-and-reverse) rule on the spherical registration:

• Forward — every target vertex takes the value of its nearest source vertex on ?h.sphere.reg.
• Reverse — any source vertex that no target selected (an "orphan") is folded into its nearest target, so no source data is dropped. This is what makes downsampling an average rather than a subsampling.

This PR builds that sparse matrix directly from ?h.sphere.reg with two KDTree queries — no subprocess, no random probing, deterministic.

Correctness

Verified against the real mri_surf2surf binary:

• individual-subject ↔ fsaverage and subject ↔ subject, both hemispheres: bit-exact (corr = 1.0, maxdiff ~2e-7).
• The one documented inexact case is the regular icosahedral targets (fsaverage6/5/4/3): many fine vertices sit exactly equidistant between two coarse vertices, and FreeSurfer breaks those ties by an internal vertex ordering this implementation does not reproduce (corr ~0.997–0.9999). The numerical difference is tiny (the alternative neighbor is the same distance away) and is documented inline rather than chased.

API / compatibility

• Same name and return type ((n_target, n_source) sparse matrix, applied as matrix.dot(source_data)); database.get_mri_surf2surf_matrix caching and Vertex.to_other_subject() are unaffected.
• surface_type is now vestigial (the correspondence depends only on the spherical registration, identical across a subject's surfaces) but kept for signature compatibility.
• Legacy regression kwargs (n_neighbors, n_test_images, ...) are accepted with a DeprecationWarning and ignored; unknown kwargs raise TypeError.
• Removed the now-unused scipy.linalg.lstsq import.

Tests

• 9 FreeSurfer-free unit tests: identity when src==trg, rows sum to 1, constant-map preservation, the no-source-dropped invariant, a hand-computed averaging example, and legacy/unknown-kwarg handling.
• 2 FreeSurfer-gated integration tests using only standard fsaverage templates (no individual subject IDs): fsaverage→fsaverage identity (bit-exact vs binary) and fsaverage→fsaverage6 downsample (corr check). They skip when mri_surf2surf is unavailable.

🤖 Generated with Claude Code

[mvdoc]

Reopening against gallantlab/pycortex upstream.

[gemini-code-assist]

Code Review

This pull request introduces several enhancements and bug fixes to pycortex, notably refactoring the surface-to-surface resampling matrix calculation to be geometry-based rather than regression-based, and fixing alpha-blending/compositing issues in the WebGL viewer by premultiplying alpha for VertexRGB and colormap textures. It also improves headless viewer loading synchronization, replaces deprecated np.in1d calls with np.isin, and adds comprehensive regression tests and a new example for plotting data with alpha. One review comment was kept, which suggests defensively checking the split parts of the Inkscape version output to prevent a potential IndexError.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

If the output of inkscape --version contains a line starting with 'Inkscape' but has no version number or other words (e.g., just the word 'Inkscape'), calling line.split()[1] will raise an IndexError. We should defensively check the length of the split parts before accessing the second element.

Suggested change

	for line in combined.splitlines():
	if line.strip().startswith('Inkscape'):
	version = line.split()[1]
	return version
	for line in combined.splitlines():
	if line.strip().startswith('Inkscape'):
	parts = line.split()
	if len(parts) > 1:
	return parts[1]