Extract scalp-projected sensor locations as DigMontage

[sappelhoff]

Describe the new feature or enhancement

• xref: https://mne.discourse.group/t/eeg-dipole-fitting-using-fsaverage-are-projected-sensors-used/11055/7?u=sappelhoff

When using mne.viz.plot_alignment (and in all forward modelling code), EEG sensors are projected onto the scalp, even if they are actually within, or outside of the skull.

See for example the dark red discs (scalp-projected sensors) versus the light red balls (actual sensor positions):

This projection happens in this private function:

mne-python/mne/surface.py

Lines 447 to 472 in 618932d

	def _project_onto_surface(
	rrs, surf, project_rrs=False, return_nn=False, method="accurate"
	):
	"""Project points onto (scalp) surface."""
	if method == "accurate":
	surf_geom = _get_tri_supp_geom(surf)
	pt_tris = np.empty((0,), int)
	pt_lens = np.zeros(len(rrs) + 1, int)
	out = _find_nearest_tri_pts(rrs, pt_tris, pt_lens, reproject=True, **surf_geom)
	if project_rrs: #
	out += (np.einsum("ij,ijk->ik", out[0], surf["rr"][surf["tris"][out[1]]]),)
	if return_nn:
	out += (surf_geom["nn"][out[1]],)
	else: # nearest neighbor
	assert project_rrs
	idx = _compute_nearest(surf["rr"], rrs)
	out = (None, None, surf["rr"][idx])
	if return_nn:
	surf_geom = _get_tri_supp_geom(surf)
	nn = _accumulate_normals(
	surf["tris"].astype(int), surf_geom["nn"], len(surf["rr"])
	)
	nn = nn[idx]
	_normalize_vectors(nn)
	out += (nn,)
	return out

It would be a nice feature to be able to extract these scalp-projected sensor positions for downstream analyses, or for creating "realistic/biological' sensor positions ... or simply to have the data that is then actually being used in forward modelling.

I also believe that we could benefit from documenting more clearly that all forward modelling (including fit_dipoles etc.) is using the scalp-projected sensor positions.

Describe your proposed implementation

Write a public version of _project_onto_surface that works well with fsaverage out of the box, or any other scalp surface that is passed into it. The function should return a DigMontage.

Add this functionality to a tutorial/example to showcase it.

And also document better that these positions are used in forward modelling.

Describe possible alternatives

Alternatively, we could start by first only documenting that scalp-projected sensors are being used.

Additional context

No response