Add VTK-free HTML surface reports and threemica bridge

README.rst

@@ -14,6 +14,56 @@ brain-derived features, together with tools to generate spatial null models.
 For installation instructions, examples and documentation of BrainSpace see
 our `documentation <https://brainspace.readthedocs.io>`_.
 
+Display-independent surface reports
+-----------------------------------
+
+BrainSpace can export browser-readable HTML surface reports without opening a
+VTK render window. This is useful on remote servers, CI runners, notebooks, and
+containers where interactive VTK rendering is unavailable.
+
+.. raw:: html
+
+   <video src="docs/_static/brainspace_threemica_bridge_preview.mp4" controls muted loop playsinline style="max-width: 100%;"></video>
+
+If the video player is not shown, open the
+`BrainSpace threemica bridge preview video <docs/_static/brainspace_threemica_bridge_preview.mp4>`_.
+The preview is generated from BrainSpace's bundled Conte69/fsLR-32k reference
+surfaces and maps; it does not contain participant data.
+
+The native BrainSpace HTML writer keeps the dependency surface small:
+
+.. code-block:: python
+
+   from brainspace.plotting import write_surface_report
+
+   report = write_surface_report(
+       surfaces={"lh": surf_lh, "rh": surf_rh},
+       arrays={"Gradient 1": gradient_1},
+       filename="surface_report.html",
+       title="BrainSpace surface report",
+   )
+
+The optional threemica bridge preserves Zhengchen Cai's original viewer and
+converts BrainSpace surfaces/maps into the BIDS-style derivative layout that
+threemica reads:
+
+.. code-block:: python
+
+   from brainspace.plotting import write_brainspace_threemica_report
+
+   reports = write_brainspace_threemica_report(
+       "brainspace_threemica_report",
+       maps=["thickness", "fc_gradient1"],
+       custom_maps={
+           "aligned_gradient": {
+               "values": aligned_gradients,
+               "label": "Aligned gradient",
+               "unit": "score",
+               "cmap": "diverging",
+           },
+       },
+   )
+
 Happy gradient analysis! 
 
 License
@@ -40,4 +90,3 @@ Core development team
 * Reinder Vos de Wael, MICA Lab - Montreal Neurological Institute
 * Oualid Benkarim, MICA Lab - Montreal Neurological Institute
 * Boris Bernhardt, MICA Lab - Montreal Neurological Institute
-

brainspace/plotting/__init__.py

@@ -1,6 +1,25 @@
-from .surface_plotting import build_plotter, plot_surf, plot_hemispheres
+from .surface_report import write_surface_report
+from .threemica_report import (available_threemica_surface_maps,
+                               write_brainspace_threemica_report,
+                               write_threemica_report)
 
 
 __all__ = ['build_plotter',
            'plot_surf',
-           'plot_hemispheres']
+           'plot_hemispheres',
+           'write_surface_report',
+           'available_threemica_surface_maps',
+           'write_brainspace_threemica_report',
+           'write_threemica_report']
+
+
+def __getattr__(name):
+    if name in {'build_plotter', 'plot_surf', 'plot_hemispheres'}:
+        from .surface_plotting import build_plotter, plot_surf, plot_hemispheres
+        globals().update({
+            'build_plotter': build_plotter,
+            'plot_surf': plot_surf,
+            'plot_hemispheres': plot_hemispheres,
+        })
+        return globals()[name]
+    raise AttributeError("module {!r} has no attribute {!r}".format(__name__, name))

brainspace/plotting/surface_plotting.py

@@ -495,7 +495,8 @@ def plot_hemispheres(surf_lh, surf_rh, array_name=None, color_bar=False,
                      cmap='viridis', nan_color=(0, 0, 0, 1), zoom=1,
                      background=(1, 1, 1), size=(400, 400), interactive=True,
                      embed_nb=False, screenshot=False, filename=None,
-                     scale=(1, 1), transparent_bg=True, **kwargs):
+                     scale=(1, 1), transparent_bg=True, backend='vtk',
+                     title='BrainSpace Surface Report', **kwargs):
     """Plot left and right hemispheres in lateral and medial views.
 
     Parameters
@@ -548,6 +549,12 @@ def plot_hemispheres(surf_lh, surf_rh, array_name=None, color_bar=False,
     scale : tuple, optional
         Scale (magnification). Only used if ``screenshot==True``.
         Default is None.
+    backend : {'vtk', 'html'}, optional
+        Rendering backend. The default ``'vtk'`` preserves the existing VTK
+        behavior. ``'html'`` writes a display-independent HTML report to
+        ``filename`` and does not initialize VTK rendering.
+    title : str, optional
+        Title used when ``backend='html'``.
     kwargs : keyword-valued args
         Additional arguments passed to the plotter.
 
@@ -563,6 +570,18 @@ def plot_hemispheres(surf_lh, surf_rh, array_name=None, color_bar=False,
     :func:`plot_surf`
 
     """
+    if backend not in {'vtk', 'html'}:
+        raise ValueError("backend must be either 'vtk' or 'html'.")
+    if backend == 'html':
+        if filename is None:
+            raise ValueError("filename is required when backend='html'.")
+        from .surface_report import write_surface_report
+        return write_surface_report({'lh': surf_lh, 'rh': surf_rh},
+                                    arrays=array_name, filename=filename,
+                                    title=title, cmap=cmap,
+                                    color_range=color_range,
+                                    nan_color=nan_color)
+
     if color_bar is True:
         color_bar = 'right'