Repository: nilearn/nilearn

Issue:
expose `vol_to_surf` parameters in `view_img_on_surf`?
I wonder if we should allow users to specify parameters for the volume to surface projection when using `view_img_on_surf`. This would help explore the effect of these parameters. moreover, for discrete images such as atlases the default parameters of `vol_to_surf` are not appropriate.

Being able to disable interpolation would allow better plots for discrete images.

   ```python 
   from nilearn import datasets, plotting
   cmap = "gist_ncar"

   destrieux = datasets.fetch_atlas_destrieux_2009()
   plotting.view_img_on_surf(destrieux.maps, surf_mesh="fsaverage", cmap=cmap,
                             symmetric_cmap=False).open_in_browser()
   plotting.view_img_on_surf(
       destrieux.maps, surf_mesh="fsaverage",
       vol_to_surf_params={"n_samples": 1, "radius": 0.,
                           "interpolation": "nearest"},
       cmap=cmap, symmetric_cmap=False).open_in_browser()
   ```

![newplot(1)](https://user-images.githubusercontent.com/9196501/66900401-0750a200-effd-11e9-858a-1cb90a2f2604.png)

![newplot](https://user-images.githubusercontent.com/9196501/66900415-0f104680-effd-11e9-8d0e-5e660da55107.png)

or simply help getting a notion of voxel and mesh resolutions

![newplot(1)](https://user-images.githubusercontent.com/9196501/66900447-1cc5cc00-effd-11e9-88ac-26a34ac9a0c9.png)



Discussion:
> being able to disable interpolation would allow better plots for discrete images

This one does seem relevant.

I am not sure that I would expose the rest: they can use the lower-level
functions.

Gael Varoquaux <notifications@github.com> writes:

>> being able to disable interpolation would allow better plots for discrete images
>
> This one does seem relevant.
>
> I am not sure that I would expose the rest: they can use the lower-level
> functions.

it needs to be interpolation + radius of the cloud of sample points,
i.e. to exactly the value of the image at the mesh node we need to set
radius=0 and interpolation="nearest"

keen to look at this one today
I think a demo explaining parameters impact is important here.

Resolving patch:
diff --git a/examples/01_plotting/plot_3d_map_to_surface_projection.py b/examples/01_plotting/plot_3d_map_to_surface_projection.py
--- a/examples/01_plotting/plot_3d_map_to_surface_projection.py
+++ b/examples/01_plotting/plot_3d_map_to_surface_projection.py
@@ -148,3 +148,25 @@
 # view.open_in_browser()
 
 view
+
+##############################################################################
+# Impact of plot parameters on visualization
+# ------------------------------------------
+# You can specify arguments to be passed on to the function
+# :func:`nilearn.plotting.vol_to_surf` using `vol_to_surf_kwargs`. This allows
+# fine-grained control of how the input 3D image is resampled and interpolated -
+# for example if you are viewing a volumetric atlas, you would want to avoid
+# averaging the labels between neighboring regions. Using nearest-neighbor
+# interpolation with zero radius will achieve this.
+
+destrieux = datasets.fetch_atlas_destrieux_2009()
+
+view = plotting.view_img_on_surf(
+    destrieux.maps,
+    surf_mesh="fsaverage",
+    vol_to_surf_kwargs={"n_samples": 1, "radius": 0.0, "interpolation": "nearest"},
+    symmetric_cmap=False,
+)
+
+# view.open_in_browser()
+view
diff --git a/nilearn/plotting/html_surface.py b/nilearn/plotting/html_surface.py
--- a/nilearn/plotting/html_surface.py
+++ b/nilearn/plotting/html_surface.py
@@ -129,7 +129,7 @@ def view_img_on_surf(stat_map_img, surf_mesh='fsaverage5',
                      threshold=None, cmap=cm.cold_hot,
                      black_bg=False, vmax=None, vmin=None, symmetric_cmap=True,
                      colorbar=True, colorbar_height=.5, colorbar_fontsize=25,
-                     title=None, title_fontsize=25):
+                     title=None, title_fontsize=25, vol_to_surf_kwargs={}):
     """Insert a surface plot of a statistical map into an HTML page.
 
     Parameters
@@ -192,6 +192,13 @@ def view_img_on_surf(stat_map_img, surf_mesh='fsaverage5',
     title_fontsize : int, optional
         Fontsize of the title. Default=25.
 
+    vol_to_surf_kwargs : dict, optional
+        Dictionary of keyword arguments that are passed on to
+        :func:`nilearn.surface.vol_to_surf` when extracting a surface from
+        the input image. See the function documentation for details.This
+        parameter is especially useful when plotting an atlas. See
+        https://nilearn.github.io/auto_examples/01_plotting/plot_3d_map_to_surface_projection.html
+
     Returns
     -------
     SurfaceView : plot of the stat map.
@@ -211,7 +218,7 @@ def view_img_on_surf(stat_map_img, surf_mesh='fsaverage5',
     info = full_brain_info(
         volume_img=stat_map_img, mesh=surf_mesh, threshold=threshold,
         cmap=cmap, black_bg=black_bg, vmax=vmax, vmin=vmin,
-        symmetric_cmap=symmetric_cmap)
+        symmetric_cmap=symmetric_cmap, vol_to_surf_kwargs=vol_to_surf_kwargs)
     info['colorbar'] = colorbar
     info['cbar_height'] = colorbar_height
     info['cbar_fontsize'] = colorbar_fontsize


Test patch:
diff --git a/nilearn/plotting/tests/test_html_surface.py b/nilearn/plotting/tests/test_html_surface.py
--- a/nilearn/plotting/tests/test_html_surface.py
+++ b/nilearn/plotting/tests/test_html_surface.py
@@ -159,3 +159,9 @@ def test_view_img_on_surf():
     np.clip(get_data(img), 0, None, out=get_data(img))
     html = html_surface.view_img_on_surf(img, symmetric_cmap=False)
     check_html(html)
+    html = html_surface.view_img_on_surf(img, symmetric_cmap=False,
+                                         vol_to_surf_kwargs={
+                                             "n_samples": 1,
+                                             "radius": 0.,
+                                             "interpolation": "nearest"})
+    check_html(html)