From 56e522ba303fe01a25a2a0d5d7507639a83fe02c Mon Sep 17 00:00:00 2001
From: Eric Larson <larson.eric.d@gmail.com>
Date: Fri, 18 Oct 2024 14:06:44 -0400
Subject: [PATCH] ENH: Improve report usability (#12901)

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: Daniel McCloy <dan@mccloy.info>
---
 doc/changes/devel/12901.bugfix.rst           |   1 +
 doc/changes/devel/12901.newfeature.rst       |   8 +
 mne/html_templates/report/html.html.jinja    |   8 +-
 mne/html_templates/report/image.html.jinja   |  26 +-
 mne/html_templates/report/section.html.jinja |   8 +-
 mne/html_templates/report/slider.html.jinja  |  12 +-
 mne/report/report.py                         | 444 ++++++++++++++-----
 mne/report/tests/test_report.py              |  79 +++-
 mne/utils/docs.py                            |  22 +-
 mne/viz/_3d.py                               |  60 ++-
 mne/viz/tests/test_3d.py                     |   6 +-
 tutorials/intro/70_report.py                 |  20 +-
 tutorials/preprocessing/59_head_positions.py |   2 +-
 13 files changed, 510 insertions(+), 186 deletions(-)
 create mode 100644 doc/changes/devel/12901.bugfix.rst
 create mode 100644 doc/changes/devel/12901.newfeature.rst

diff --git a/doc/changes/devel/12901.bugfix.rst b/doc/changes/devel/12901.bugfix.rst
new file mode 100644
index 00000000000..d68f70f7141
--- /dev/null
+++ b/doc/changes/devel/12901.bugfix.rst
@@ -0,0 +1 @@
+:class:`mne.Report` HDF5 files are now written in ``mode='a'`` (append) to allow users to store other data in the HDF5 files, by `Eric Larson`_.
diff --git a/doc/changes/devel/12901.newfeature.rst b/doc/changes/devel/12901.newfeature.rst
new file mode 100644
index 00000000000..8d0137fce78
--- /dev/null
+++ b/doc/changes/devel/12901.newfeature.rst
@@ -0,0 +1,8 @@
+Improved reporting and plotting options:
+
+- :meth:`mne.Report.add_projs` can now plot with :func:`mne.viz.plot_projs_joint` rather than :func:`mne.viz.plot_projs_topomap`
+- :class:`mne.Report` now has attributes ``img_max_width`` and ``img_max_res`` that can be used to control image scaling.
+- :class:`mne.Report` now has an attribute ``collapse`` that allows collapsing sections and/or subsections by default.
+- :func:`mne.viz.plot_head_positions` now has a ``totals=True`` option to show the total distance and angle of the head.
+
+Changes by `Eric Larson`_.
diff --git a/mne/html_templates/report/html.html.jinja b/mne/html_templates/report/html.html.jinja
index 62b9da07911..a9b4f881f12 100644
--- a/mne/html_templates/report/html.html.jinja
+++ b/mne/html_templates/report/html.html.jinja
@@ -1,7 +1,6 @@
 <div class="accordion-item {{ div_klass }}" id="{{ id }}" data-mne-tags="{% for tag in tags %} {{ tag }} {% endfor %}">
   <div class="accordion-header" id="accordion-header-{{id}}">
-    <button class="accordion-button pt-1 pb-1" type="button" data-bs-toggle="collapse"
-      data-bs-target="#accordion-collapse-{{ id }}" aria-expanded="true" aria-controls="accordion-collapse-{{id}}">
+    <button class="accordion-button pt-1 pb-1" type="button" data-bs-toggle="collapse" data-bs-target="#accordion-collapse-{{ id }}" aria-expanded="true" aria-controls="accordion-collapse-{{id}}">
       <div class="w-100">
         <span class="me-auto"><a href="#{{ id }}" class="text-decoration-none">{{ title }}</a></span>
         {% for tag in tags %}
@@ -12,10 +11,7 @@
       </div>
     </button>
   </div>
-
-
-  <div id="accordion-collapse-{{ id }}" class="accordion-collapse collapse show"
-    aria-labelledby="accordion-header-{{ id }}">
+  <div id="accordion-collapse-{{ id }}" class="accordion-collapse collapse {{ show }}" aria-labelledby="accordion-header-{{ id }}">
     <div class="accordion-body">
       {{ html | safe }}
     </div>
diff --git a/mne/html_templates/report/image.html.jinja b/mne/html_templates/report/image.html.jinja
index 06a6855ace5..41cf47e1395 100644
--- a/mne/html_templates/report/image.html.jinja
+++ b/mne/html_templates/report/image.html.jinja
@@ -1,17 +1,17 @@
 {% extends "section.html.jinja" %}
 {% block html_content %}
-<figure class="figure mx-auto d-block">
-  {% if image_format == 'svg' %}
-  <div class="d-flex justify-content-center">
-    {{ img|safe }}
-  </div>
-  {% else %}
-  <img class="figure-img img-fluid rounded mx-auto my-0 d-block" alt="{{ title }}"
-    src="data:image/{{ image_format }};base64,{{ img }}">
-  {% endif %}
+      <figure class="figure mx-auto d-block">
+        {% if image_format == 'svg' %}
+        <div class="d-flex justify-content-center">
+          {{ img|safe }}
+        </div>
+        {% else %}
+        <img class="figure-img img-fluid rounded mx-auto my-0 d-block" alt="{{ title }}"
+          src="data:image/{{ image_format }};base64,{{ img }}">
+        {% endif %}
 
-  {% if caption is not none %}
-  <figcaption class="figure-caption text-center">{{ caption }}</figcaption>
-  {% endif %}
-</figure>
+        {% if caption is not none %}
+        <figcaption class="figure-caption text-center">{{ caption }}</figcaption>
+        {% endif %}
+      </figure>
 {% endblock html_content %}
diff --git a/mne/html_templates/report/section.html.jinja b/mne/html_templates/report/section.html.jinja
index 584ff86dda9..baddf7dd8b6 100644
--- a/mne/html_templates/report/section.html.jinja
+++ b/mne/html_templates/report/section.html.jinja
@@ -1,7 +1,6 @@
 <div class="accordion-item {{ div_klass }}" id="{{ id }}" data-mne-tags="{% for tag in tags %} {{ tag }} {% endfor %}">
   <div class="accordion-header" id="accordion-header-{{id}}">
-    <button class="accordion-button pt-1 pb-1" type="button" data-bs-toggle="collapse"
-      data-bs-target="#accordion-collapse-{{ id }}" aria-expanded="true" aria-controls="accordion-collapse-{{id}}">
+    <button class="accordion-button pt-1 pb-1" type="button" data-bs-toggle="collapse" data-bs-target="#accordion-collapse-{{ id }}" aria-expanded="true" aria-controls="accordion-collapse-{{id}}">
       <div class="w-100">
         <span class="me-auto"><a href="#{{ id }}" class="text-decoration-none">{{ title }}</a></span>
         {% for tag in tags %}
@@ -12,10 +11,7 @@
       </div>
     </button>
   </div>
-
-
-  <div id="accordion-collapse-{{ id }}" class="accordion-collapse collapse show"
-    aria-labelledby="accordion-header-{{ id }}">
+  <div id="accordion-collapse-{{ id }}" class="accordion-collapse collapse {{ show }}" aria-labelledby="accordion-header-{{ id }}">
     <div class="accordion-body">
       {% block html_content %}
       {% for html in htmls %}
diff --git a/mne/html_templates/report/slider.html.jinja b/mne/html_templates/report/slider.html.jinja
index 58ee8a9f9fc..fab7f56472d 100644
--- a/mne/html_templates/report/slider.html.jinja
+++ b/mne/html_templates/report/slider.html.jinja
@@ -1,8 +1,7 @@
 <div class="accordion-item slider {{ klass }}" id="{{ id }}"
   data-mne-tags="{% for tag in tags %} {{ tag }} {% endfor %}">
   <div class="accordion-header" id="accordion-header-{{ id }}">
-    <button class="accordion-button pt-1 pb-1" type="button" data-bs-toggle="collapse"
-      data-bs-target="#accordion-collapse-{{ id }}" aria-expanded="true" aria-controls="accordion-collapse-{{ id }}">
+    <button class="accordion-button pt-1 pb-1" type="button" data-bs-toggle="collapse" data-bs-target="#accordion-collapse-{{ id }}" aria-expanded="true" aria-controls="accordion-collapse-{{ id }}">
       <div class="w-100">
         <span class="me-auto"><a href="#{{ id }}" class="text-decoration-none">{{ title }}</a></span>
         {% for tag in tags %}
@@ -13,9 +12,7 @@
       </div>
     </button>
   </div>
-
-  <div id="accordion-collapse-{{ id }}" class="accordion-collapse collapse show"
-    aria-labelledby="accordion-header-{{ id }}">
+  <div id="accordion-collapse-{{ id }}" class="accordion-collapse collapse {{ show }}" aria-labelledby="accordion-header-{{ id }}">
     <div class=" accordion-body">
       <div class="mx-auto d-block w-75">
         <label for="slider-{{ id }}" class="form-label small">
@@ -24,9 +21,7 @@
         <input type="range" class="form-range" min="0" max="{{ images|length - 1 }}" value="{{ start_idx }}"
           id="slider-{{id}}">
       </div>
-
-      <div id="corousel-{{ id }}" class="carousel carousel-dark" data-bs-interval="false" data-bs-wrap="false"
-        data-bs-keyboard="true">
+      <div id="corousel-{{ id }}" class="carousel carousel-dark" data-bs-interval="false" data-bs-wrap="false" data-bs-keyboard="true">
         <div class="carousel-inner">
           {% for idx, img, caption in range(images|length)|zip(images, captions) %}
           <div class="carousel-item {% if idx == start_idx %}active{% endif %}">
@@ -40,7 +35,6 @@
           </div>
           {% endfor %}
         </div>
-
         {# <button class="carousel-control-prev" type="button" data-bs-target="#corousel-{{id}}" data-bs-slide="prev">
           <span class="carousel-control-prev-icon" aria-hidden="true"></span>
           <span class="visually-hidden">Previous</span>
diff --git a/mne/report/report.py b/mne/report/report.py
index 0ca781378f5..7cab9774c8e 100644
--- a/mne/report/report.py
+++ b/mne/report/report.py
@@ -9,7 +9,6 @@
 import base64
 import copy
 import dataclasses
-import io
 import os
 import os.path as op
 import re
@@ -75,6 +74,7 @@
     plot_compare_evokeds,
     plot_cov,
     plot_events,
+    plot_projs_joint,
     plot_projs_topomap,
     set_3d_view,
     use_browser_backend,
@@ -205,7 +205,7 @@ def _html_inverse_operator_element(*, id_, repr_, source_space, title, tags):
 
 
 def _html_slider_element(
-    *, id_, images, captions, start_idx, image_format, title, tags, klass=""
+    *, id_, images, captions, start_idx, image_format, title, tags, show, klass=""
 ):
     captions_ = []
     for caption in captions:
@@ -223,6 +223,7 @@ def _html_slider_element(
         start_idx=start_idx,
         image_format=image_format,
         klass=klass,
+        show="show" if show else "",
     )
 
 
@@ -238,7 +239,7 @@ def _html_image_element(
         image_format=image_format,
         div_klass=div_klass,
         img_klass=img_klass,
-        show=show,
+        show="show" if show else "",
     )
 
 
@@ -252,13 +253,14 @@ def _html_code_element(*, id_, code, language, title, tags):
     )
 
 
-def _html_section_element(*, id_, div_klass, htmls, title, tags):
+def _html_section_element(*, id_, div_klass, htmls, title, tags, show):
     return _renderer("section.html.jinja")(
         id=id_,
         div_klass=div_klass,
         htmls=htmls,
         title=title,
         tags=tags,
+        show="show" if show else "",
     )
 
 
@@ -283,13 +285,14 @@ def _html_bem_element(
     )
 
 
-def _html_element(*, id_, div_klass, html, title, tags):
+def _html_element(*, id_, div_klass, html, title, tags, show):
     return _renderer("html.html.jinja")(
         id=id_,
         div_klass=div_klass,
         html=html,
         title=title,
         tags=tags,
+        show="show" if show else "",
     )
 
 
@@ -352,20 +355,35 @@ def _constrain_fig_resolution(fig, *, max_width, max_res):
     ----------
     fig : matplotlib.figure.Figure
         The figure whose DPI to adjust.
-    max_width : int
+    max_width : int | None
         The max. allowed width, in pixels.
-    max_res : int
+    max_res : float | None
         The max. allowed resolution, in DPI.
 
     Returns
     -------
     Nothing, alters the figure's properties in-place.
     """
-    dpi = min(max_res, max_width / fig.get_size_inches()[0])
-    fig.set_dpi(dpi)
-
-
-def _fig_to_img(fig, *, image_format="png", own_figure=True):
+    dpi = orig_dpi = fig.get_dpi()
+    # Limited by figure width?
+    if max_width is not None:
+        dpi = min(dpi, max_width / fig.get_size_inches()[0])
+    # Limited by resolution?
+    if max_res is not None:
+        dpi = min(dpi, max_res)
+    if orig_dpi != dpi:
+        fig.set_dpi(dpi)
+
+
+def _fig_to_img(
+    fig,
+    *,
+    image_format="png",
+    own_figure=True,
+    max_width=MAX_IMG_WIDTH,
+    max_res=MAX_IMG_RES,
+    **mpl_kwargs,
+):
     """Plot figure and create a binary image."""
     # fig can be ndarray, mpl Figure, PyVista Figure
     import matplotlib.pyplot as plt
@@ -376,10 +394,11 @@ def _fig_to_img(fig, *, image_format="png", own_figure=True):
         # auto-close in all cases
         fig = _ndarray_to_fig(fig)
         if own_figure:
-            _constrain_fig_resolution(fig, max_width=MAX_IMG_WIDTH, max_res=MAX_IMG_RES)
+            _constrain_fig_resolution(fig, max_width=max_width, max_res=max_res)
         own_figure = True  # close the figure we just created
     elif isinstance(fig, Figure):
-        pass  # nothing to do
+        if own_figure:
+            _constrain_fig_resolution(fig, max_width=max_width, max_res=max_res)
     else:
         # Don't attempt a mne_qt_browser import here (it might pull in Qt
         # libraries we don't want), so use a probably good enough class name
@@ -404,7 +423,7 @@ def _fig_to_img(fig, *, image_format="png", own_figure=True):
             )
         fig = _ndarray_to_fig(img)
         if own_figure:
-            _constrain_fig_resolution(fig, max_width=MAX_IMG_WIDTH, max_res=MAX_IMG_RES)
+            _constrain_fig_resolution(fig, max_width=max_width, max_res=max_res)
         own_figure = True  # close the fig we just created
 
     output = BytesIO()
@@ -415,7 +434,6 @@ def _fig_to_img(fig, *, image_format="png", own_figure=True):
     )
 
     # https://pillow.readthedocs.io/en/stable/handbook/image-file-formats.html
-    mpl_kwargs = dict()
     pil_kwargs = dict()
     if image_format == "webp":
         pil_kwargs.update(lossless=True, method=6)
@@ -425,13 +443,16 @@ def _fig_to_img(fig, *, image_format="png", own_figure=True):
         # matplotlib modifies the passed dict, which is a bug
         mpl_kwargs["pil_kwargs"] = pil_kwargs.copy()
 
-    fig.savefig(output, format=image_format, dpi=dpi, **mpl_kwargs)
+    mpl_format = image_format
+    if image_format == "ndarray":
+        mpl_format = "png"
+    fig.savefig(output, format=mpl_format, dpi=dpi, **mpl_kwargs)
 
     if own_figure:
         plt.close(fig)
 
     # Remove alpha
-    if image_format != "svg":
+    if image_format not in ("svg", "ndarray"):
         from PIL import Image
 
         output.seek(0)
@@ -442,12 +463,16 @@ def _fig_to_img(fig, *, image_format="png", own_figure=True):
             output = BytesIO()
             new.save(output, format=image_format, dpi=(dpi, dpi), **pil_kwargs)
 
-    output = output.getvalue()
-    return (
-        output.decode("utf-8")
-        if image_format == "svg"
-        else base64.b64encode(output).decode("ascii")
-    )
+    if image_format == "ndarray":
+        output.seek(0)
+        output = plt.imread(output, format="png")
+    else:
+        output = output.getvalue()
+        if image_format == "svg":
+            output = output.decode("utf-8")
+        else:
+            output = base64.b64encode(output).decode("ascii")
+    return output
 
 
 def _get_bem_contour_figs_as_arrays(
@@ -501,7 +526,7 @@ def _iterate_trans_views(function, alpha, **kwargs):
         backend._close_3d_figure(fig)
 
 
-def _itv(function, fig, **kwargs):
+def _itv(function, fig, *, max_width=MAX_IMG_WIDTH, max_res=MAX_IMG_RES, **kwargs):
     from ..viz.backends.renderer import MNE_3D_BACKEND_TESTING, backend
 
     function(fig=fig, **kwargs)
@@ -537,12 +562,14 @@ def _itv(function, fig, **kwargs):
     except BaseException as e:
         caption = "Distances could not be calculated from digitized points"
         warn(f"{caption}: {e}")
-    img = _fig_to_img(images, image_format="png")
+    img = _fig_to_img(images, image_format="png", max_width=max_width, max_res=max_res)
 
     return img, caption
 
 
-def _plot_ica_properties_as_arrays(*, ica, inst, picks, n_jobs):
+def _plot_ica_properties_as_arrays(
+    *, ica, inst, picks, n_jobs, max_width=MAX_IMG_WIDTH, max_res=MAX_IMG_RES
+):
     """Parallelize ICA component properties plotting, and return arrays.
 
     Returns
@@ -550,24 +577,17 @@ def _plot_ica_properties_as_arrays(*, ica, inst, picks, n_jobs):
     outs : list of array
         The properties plots as NumPy arrays.
     """
-    import matplotlib.pyplot as plt
 
     def _plot_one_ica_property(*, ica, inst, pick):
         figs = ica.plot_properties(inst=inst, picks=pick, show=False)
         assert len(figs) == 1
-        fig = figs[0]
-        _constrain_fig_resolution(fig, max_width=MAX_IMG_WIDTH, max_res=MAX_IMG_RES)
-        with io.BytesIO() as buff:
-            fig.savefig(
-                buff,
-                format="png",
-                pad_inches=0,
-            )
-            buff.seek(0)
-            fig_array = plt.imread(buff, format="png")
-
-        plt.close(fig)
-        return fig_array
+        return _fig_to_img(
+            figs[0],
+            max_width=max_width,
+            max_res=max_res,
+            image_format="ndarray",
+            pad_inches=0,
+        )
 
     parallel, p_fun, n_jobs = parallel_func(
         func=_plot_one_ica_property, n_jobs=n_jobs, max_jobs=len(picks)
@@ -600,6 +620,13 @@ def _endswith(fname: str | Path, suffixes):
     return False
 
 
+_backward_compat_map = dict(
+    img_max_width=MAX_IMG_WIDTH,
+    img_max_res=MAX_IMG_RES,
+    collapse=(),
+)
+
+
 def open_report(fname, **params):
     """Read a saved report or, if it doesn't exist yet, create a new one.
 
@@ -628,13 +655,16 @@ def open_report(fname, **params):
         # Check **params with the loaded report
         read_hdf5, _ = _import_h5io_funcs()
         state = read_hdf5(fname, title="mnepython")
-        for param in params.keys():
+        for param in params:
             if param not in state:
-                raise ValueError(f"The loaded report has no attribute {param}")
+                if param in _backward_compat_map:
+                    state[param] = _backward_compat_map[param]
+                else:
+                    raise ValueError(f"The loaded report has no attribute {param}")
             if params[param] != state[param]:
                 raise ValueError(
-                    f"Attribute '{param}' of loaded report does not "
-                    "match the given parameter."
+                    f"Attribute '{param}' of loaded report ({params[param]}) does not "
+                    f"match the given parameter ({state[param]})."
                 )
         report = Report()
         report.__setstate__(state)
@@ -708,6 +738,19 @@ class Report:
         the data. Defaults to ``False``.
 
         .. versionadded:: 0.21
+    img_max_width : int | None
+        Maximum image width in pixels.
+
+        .. versionadded:: 1.9
+    img_max_res : float | None
+        Maximum image resolution in dots per inch.
+
+        .. versionadded:: 1.9
+    collapse : tuple of str | str
+        Tuple of elements to collapse by default. Defaults to an empty tuple.
+        For now the only option it can contain is "section".
+
+        .. versionadded:: 1.9
     %(verbose)s
 
     Attributes
@@ -751,6 +794,18 @@ class Report:
         List of sections.
     lang : str
         language setting for the HTML file.
+    img_max_width : int | None
+        Maximum image width in pixels.
+
+        .. versionadded:: 1.9
+    img_max_res : float | None
+        Maximum image resolution in dots per inch.
+
+        .. versionadded:: 1.9
+    collapse : tuple of str
+        Tuple of elements to collapse by default. See above.
+
+        .. versionadded:: 1.9
 
     Notes
     -----
@@ -772,6 +827,9 @@ def __init__(
         raw_psd=False,
         projs=False,
         *,
+        img_max_width=MAX_IMG_WIDTH,
+        img_max_res=MAX_IMG_RES,
+        collapse=(),
         verbose=None,
     ):
         self.info_fname = str(info_fname) if info_fname is not None else None
@@ -792,6 +850,9 @@ def __init__(
         self._content = []
         self.include = []
         self.lang = "en-us"  # language setting for the HTML file
+        self.img_max_width = img_max_width
+        self.img_max_res = img_max_res
+        self.collapse = collapse
         if not isinstance(raw_psd, bool) and not isinstance(raw_psd, dict):
             raise TypeError(f"raw_psd must be bool or dict, got {type(raw_psd)}")
         self.raw_psd = raw_psd
@@ -800,6 +861,46 @@ def __init__(
         self.fname = None  # The name of the saved report
         self.data_path = None
 
+    @property
+    def img_max_width(self):
+        return self._img_max_width
+
+    @img_max_width.setter
+    def img_max_width(self, value):
+        _validate_type(value, ("int-like", None), "img_max_width")
+        if value is not None:
+            value = int(value)
+            if value < 1:
+                raise ValueError(f"img_max_width must be at least 1, got {value}")
+        self._img_max_width = value
+
+    @property
+    def img_max_res(self):
+        return self._img_max_res
+
+    @img_max_res.setter
+    def img_max_res(self, value):
+        _validate_type(value, ("numeric", None), "img_max_res")
+        if value is not None:
+            value = float(value)
+            if value < 1:
+                raise ValueError(f"img_max_res must be at least 1, got {value}")
+        self._img_max_res = value
+
+    @property
+    def collapse(self):
+        return self._collapse
+
+    @collapse.setter
+    def collapse(self, value):
+        _validate_type(value, (list, tuple, str), "collapse")
+        if isinstance(value, str):
+            value = [value]
+        for vi, v in enumerate(value):
+            _validate_type(v, str, f"collapse[{vi}]")
+            _check_option(f"collapse[{vi}]", v, ("section",))
+        self._collapse = tuple(value)
+
     def __repr__(self):
         """Print useful info about report."""
         htmls, _, titles, _ = self._content_as_html()
@@ -861,6 +962,9 @@ def _get_state_params():
             "data_path",
             "lang",
             "fname",
+            "img_max_width",
+            "img_max_res",
+            "collapse",
         )
 
     def _get_dom_id(self, *, section, title, extra_exclude=None):
@@ -1026,6 +1130,7 @@ def _content_as_html(self):
                     tags=section_tags,
                     title=content_element.section,
                     div_klass="section",
+                    show="section" not in self.collapse,
                 )
                 htmls.append(section_html)
                 dom_ids.append(section_dom_id)
@@ -1326,6 +1431,7 @@ def add_stc(
         n_time_points=None,
         tags=("source-estimate",),
         replace=False,
+        section=None,
         stc_plot_kwargs=None,
     ):
         """Add a `~mne.SourceEstimate` (STC) to the report.
@@ -1349,6 +1455,9 @@ def add_stc(
             contains fewer time points, in which case all will be rendered.
         %(tags_report)s
         %(replace_report)s
+        %(section_report)s
+
+            .. versionadded:: 1.9
         %(stc_plot_kwargs_report)s
 
         Notes
@@ -1365,7 +1474,7 @@ def add_stc(
             subjects_dir=subjects_dir,
             n_time_points=n_time_points,
             stc_plot_kwargs=stc_plot_kwargs,
-            section=None,
+            section=section,
             replace=replace,
         )
 
@@ -1378,6 +1487,7 @@ def add_forward(
         subject=None,
         subjects_dir=None,
         tags=("forward-solution",),
+        section=None,
         replace=False,
     ):
         """Add a forward solution.
@@ -1396,6 +1506,9 @@ def add_forward(
         subjects_dir : path-like | None
             The FreeSurfer ``SUBJECTS_DIR``.
         %(tags_report)s
+        %(section_report)s
+
+            .. versionadded:: 1.9
         %(replace_report)s
 
         Notes
@@ -1410,7 +1523,7 @@ def add_forward(
             subjects_dir=subjects_dir,
             title=title,
             image_format=self.image_format,
-            section=None,
+            section=section,
             tags=tags,
             replace=replace,
         )
@@ -1425,6 +1538,7 @@ def add_inverse_operator(
         subjects_dir=None,
         trans=None,
         tags=("inverse-operator",),
+        section=None,
         replace=False,
     ):
         """Add an inverse operator.
@@ -1446,6 +1560,9 @@ def add_inverse_operator(
         trans : path-like | instance of Transform | None
             The ``head -> MRI`` transformation for ``subject``.
         %(tags_report)s
+        %(section_report)s
+
+            .. versionadded:: 1.9
         %(replace_report)s
 
         Notes
@@ -1466,7 +1583,7 @@ def add_inverse_operator(
             trans=trans,
             title=title,
             image_format=self.image_format,
-            section=None,
+            section=section,
             tags=tags,
             replace=replace,
         )
@@ -1482,6 +1599,8 @@ def add_trans(
         subjects_dir=None,
         alpha=None,
         tags=("coregistration",),
+        section=None,
+        coord_frame="mri",
         replace=False,
     ):
         """Add a coregistration visualization to the report.
@@ -1506,6 +1625,11 @@ def add_trans(
             be between 0 and 1 (inclusive), where 1 means fully opaque. If
             ``None``, will use the MNE-Python default value.
         %(tags_report)s
+        %(section_report)s
+
+            .. versionadded:: 1.9
+        coord_frame : 'auto' | 'head' | 'meg' | 'mri'
+            Coordinate frame used for plotting. See :func:`mne.viz.plot_alignment`.
         %(replace_report)s
 
         Notes
@@ -1520,8 +1644,9 @@ def add_trans(
             subjects_dir=subjects_dir,
             alpha=alpha,
             title=title,
-            section=None,
+            section=section,
             tags=tags,
+            coord_frame=coord_frame,
             replace=replace,
         )
 
@@ -1565,6 +1690,7 @@ def add_events(
         first_samp=0,
         color=None,
         tags=("events",),
+        section=None,
         replace=False,
     ):
         """Add events to the report.
@@ -1588,6 +1714,9 @@ def add_events(
 
             .. versionadded:: 1.8.0
         %(tags_report)s
+        %(section_report)s
+
+            .. versionadded:: 1.9
         %(replace_report)s
 
         Notes
@@ -1602,7 +1731,7 @@ def add_events(
             first_samp=first_samp,
             color=color,
             title=title,
-            section=None,
+            section=section,
             image_format=self.image_format,
             tags=tags,
             replace=replace,
@@ -1613,27 +1742,43 @@ def add_projs(
         self,
         *,
         info,
-        projs=None,
         title,
+        projs=None,
         topomap_kwargs=None,
         tags=("ssp",),
+        joint=False,
+        picks_trace=None,
+        section=None,
         replace=False,
     ):
         """Render (SSP) projection vectors.
 
         Parameters
         ----------
-        info : instance of Info | path-like
-            An `~mne.Info` structure or the path of a file containing one. This
-            is required to create the topographic plots.
+        info : instance of Info | instance of Evoked | path-like
+            An `~mne.Info` structure or the path of a file containing one.
+        title : str
+            The title corresponding to the :class:`~mne.Projection` object.
         projs : iterable of mne.Projection | path-like | None
             The projection vectors to add to the report. Can be the path to a
             file that will be loaded via `mne.read_proj`. If ``None``, the
             projectors are taken from ``info['projs']``.
-        title : str
-            The title corresponding to the `~mne.Projection` object.
         %(topomap_kwargs)s
         %(tags_report)s
+        joint : bool
+            If True (default False), plot the projectors using
+            :func:`mne.viz.plot_projs_joint`, otherwise use
+            :func:`mne.viz.plot_projs_topomap`. If True, then ``info`` must be an
+            instance of :class:`mne.Evoked`.
+
+            .. versionadded:: 1.9
+        %(picks_plot_projs_joint_trace)s
+            Only used when ``joint=True``.
+
+            .. versionadded:: 1.9
+        %(section_report)s
+
+            .. versionadded:: 1.9
         %(replace_report)s
 
         Notes
@@ -1646,10 +1791,11 @@ def add_projs(
             projs=projs,
             title=title,
             image_format=self.image_format,
-            section=None,
+            section=section,
             tags=tags,
             topomap_kwargs=topomap_kwargs,
             replace=replace,
+            joint=joint,
         )
 
     def _add_ica_overlay(self, *, ica, inst, image_format, section, tags, replace):
@@ -1660,7 +1806,6 @@ def _add_ica_overlay(self, *, ica, inst, image_format, section, tags, replace):
 
         fig = ica.plot_overlay(inst=inst_, show=False, on_baseline="reapply")
         del inst_
-        _constrain_fig_resolution(fig, max_width=MAX_IMG_WIDTH, max_res=MAX_IMG_RES)
         self._add_figure(
             fig=fig,
             title="Original and cleaned signal",
@@ -1688,7 +1833,12 @@ def _add_ica_properties(
             picks = list(range(ica.n_components_))
 
         figs = _plot_ica_properties_as_arrays(
-            ica=ica, inst=inst, picks=picks, n_jobs=n_jobs
+            ica=ica,
+            inst=inst,
+            picks=picks,
+            n_jobs=n_jobs,
+            max_width=MAX_IMG_WIDTH,
+            max_res=MAX_IMG_RES,
         )
         assert len(figs) == len(picks)
 
@@ -1729,7 +1879,6 @@ def _add_ica_artifact_sources(
     ):
         with use_browser_backend("matplotlib"):
             fig = ica.plot_sources(inst=inst, show=False)
-        _constrain_fig_resolution(fig, max_width=MAX_IMG_WIDTH, max_res=MAX_IMG_RES)
         self._add_figure(
             fig=fig,
             title=f"Original and cleaned {artifact_type} epochs",
@@ -1748,7 +1897,6 @@ def _add_ica_artifact_scores(
         fig = ica.plot_scores(
             scores=scores, title=None, labels=artifact_type.lower(), show=False
         )
-        _constrain_fig_resolution(fig, max_width=MAX_IMG_WIDTH, max_res=MAX_IMG_RES)
         self._add_figure(
             fig=fig,
             title=f"Scores for matching {artifact_type} patterns",
@@ -1777,7 +1925,6 @@ def _add_ica_components(self, *, ica, picks, image_format, section, tags, replac
         title = "ICA component topographies"
         if len(figs) == 1:
             fig = figs[0]
-            _constrain_fig_resolution(fig, max_width=MAX_IMG_WIDTH, max_res=MAX_IMG_RES)
             self._add_figure(
                 fig=fig,
                 title=title,
@@ -2130,7 +2277,14 @@ def _add_code(self, *, code, title, language, section, tags, replace):
 
     @fill_doc
     def add_code(
-        self, code, title, *, language="python", tags=("code",), replace=False
+        self,
+        code,
+        title,
+        *,
+        language="python",
+        tags=("code",),
+        section=None,
+        replace=False,
     ):
         """Add a code snippet (e.g., an analysis script) to the report.
 
@@ -2148,6 +2302,9 @@ def add_code(
             The programming language of ``code``. This will be used for syntax
             highlighting. Can be ``'auto'`` to try to auto-detect the language.
         %(tags_report)s
+        %(section_report)s
+
+            .. versionadded:: 1.9
         %(replace_report)s
 
         Notes
@@ -2160,7 +2317,7 @@ def add_code(
             code=code,
             title=title,
             language=language,
-            section=None,
+            section=section,
             tags=tags,
             replace=replace,
         )
@@ -2221,10 +2378,33 @@ def _add_image(
             replace=replace,
         )
 
+    def _fig_to_img(self, *, fig, image_format, own_figure=True, **mpl_kwargs):
+        return _fig_to_img(
+            fig,
+            image_format=image_format,
+            own_figure=own_figure,
+            max_width=self.img_max_width,
+            max_res=self.img_max_res,
+            **mpl_kwargs,
+        )
+
     def _add_figure(
-        self, *, fig, title, caption, image_format, tags, section, replace, own_figure
+        self,
+        *,
+        fig,
+        title,
+        caption,
+        image_format,
+        tags,
+        section,
+        replace,
+        own_figure,
     ):
-        img = _fig_to_img(fig=fig, image_format=image_format, own_figure=own_figure)
+        img = self._fig_to_img(
+            fig=fig,
+            image_format=image_format,
+            own_figure=own_figure,
+        )
         self._add_image(
             img=img,
             title=title,
@@ -2403,6 +2583,7 @@ def add_html(
             title=title,
             tags=tags,
             div_klass="custom-html",
+            show=True,
         )
         self._add_or_replace(
             title=title,
@@ -2423,6 +2604,7 @@ def add_bem(
         width=512,
         n_jobs=None,
         tags=("bem",),
+        section=None,
         replace=False,
     ):
         """Render a visualization of the boundary element model (BEM) surfaces.
@@ -2444,6 +2626,9 @@ def add_bem(
             each dimension (typically 512, default) is reasonable.
         %(n_jobs)s
         %(tags_report)s
+        %(section_report)s
+
+            .. versionadded:: 1.9
         %(replace_report)s
 
         Notes
@@ -2461,6 +2646,7 @@ def add_bem(
             image_format=self.image_format,
             title=title,
             tags=tags,
+            section=section,
             replace=replace,
         )
 
@@ -2493,7 +2679,11 @@ def _render_slider(
             )
         elif figs:  # figs can be None if imgs is provided
             imgs = [
-                _fig_to_img(fig=fig, image_format=image_format, own_figure=own_figure)
+                self._fig_to_img(
+                    fig=fig,
+                    image_format=image_format,
+                    own_figure=own_figure,
+                )
                 for fig in figs
             ]
 
@@ -2506,6 +2696,7 @@ def _render_slider(
             image_format=image_format,
             start_idx=start_idx,
             klass=klass,
+            show=True,
         )
         return html_partial
 
@@ -2970,9 +3161,10 @@ def save(
 
             if is_hdf5:
                 _, write_hdf5 = _import_h5io_funcs()
-                write_hdf5(
-                    fname, self.__getstate__(), overwrite=overwrite, title="mnepython"
-                )
+                import h5py
+
+                with h5py.File(fname, "a") as f:  # Read/write if exists, else create
+                    write_hdf5(f, self.__getstate__(), title="mnepython")
             else:
                 # Add header, TOC, and footer.
                 header_html = _html_header_element(
@@ -3132,15 +3324,14 @@ def _add_raw_butterfly_segments(
                     scalings=scalings,
                     show=False,
                 )
-            _constrain_fig_resolution(fig, max_width=MAX_IMG_WIDTH, max_res=MAX_IMG_RES)
-            images = [_fig_to_img(fig=fig, image_format=image_format)]
+            images = [self._fig_to_img(fig=fig, image_format=image_format)]
 
             for start, duration in zip(t_starts[1:], durations[1:]):
                 fig.mne.t_start = start
                 fig.mne.duration = duration
                 fig._update_hscroll()
                 fig._redraw(annotations=False)
-                images.append(_fig_to_img(fig=fig, image_format=image_format))
+                images.append(self._fig_to_img(fig=fig, image_format=image_format))
         except Exception:
             raise
         finally:
@@ -3226,7 +3417,6 @@ def _add_raw(
             with warnings.catch_warnings():
                 warnings.simplefilter(action="ignore", category=FutureWarning)
                 fig = raw.compute_psd(**init_kwargs).plot(**plot_kwargs)
-            _constrain_fig_resolution(fig, max_width=MAX_IMG_WIDTH, max_res=MAX_IMG_RES)
             self._add_figure(
                 fig=fig,
                 title="PSD",
@@ -3262,26 +3452,27 @@ def _add_projs(
         section,
         topomap_kwargs,
         replace,
+        picks_trace=None,
+        joint=False,
     ):
+        evoked = None
         if isinstance(info, Info):  # no-op
             pass
         elif hasattr(info, "info"):  # try to get the file name
-            if isinstance(info, BaseRaw):
-                fname = info.filenames[0]
-            # elif isinstance(info, (Evoked, BaseEpochs)):
-            #     fname = info.filename
-            else:
-                fname = ""
+            if isinstance(info, Evoked):
+                evoked = info
             info = info.info
         else:  # read from a file
-            fname = info
-            info = read_info(fname, verbose=False)
+            info = read_info(info, verbose=False)
+        if joint and evoked is None:
+            raise ValueError(
+                "joint=True requires an evoked instance to be passed as the info"
+            )
 
         if projs is None:
             projs = info["projs"]
         elif not isinstance(projs, list):
-            fname = projs
-            projs = read_proj(fname)
+            projs = read_proj(projs)
 
         if not projs:
             raise ValueError("No SSP projectors found")
@@ -3294,20 +3485,29 @@ def _add_projs(
             )
 
         topomap_kwargs = self._validate_topomap_kwargs(topomap_kwargs)
-        fig = plot_projs_topomap(
-            projs=projs,
-            info=info,
-            colorbar=True,
-            vlim="joint",
-            show=False,
-            **topomap_kwargs,
-        )
-        # TODO This seems like a bad idea, better to provide a way to set a
-        # desired size in plot_projs_topomap, but that uses prepare_trellis...
-        # hard to see how (6, 4) could work in all number-of-projs by
-        # number-of-channel-types conditions...
-        fig.set_size_inches((6, 4))
-        _constrain_fig_resolution(fig, max_width=MAX_IMG_WIDTH, max_res=MAX_IMG_RES)
+        if evoked is None:
+            fig = plot_projs_topomap(
+                projs=projs,
+                info=info,
+                colorbar=True,
+                vlim="joint",
+                show=False,
+                **topomap_kwargs,
+            )
+            # TODO This seems like a bad idea, better to provide a way to set a
+            # desired size in plot_projs_topomap, but that uses prepare_trellis...
+            # hard to see how (6, 4) could work in all number-of-projs by
+            # number-of-channel-types conditions...
+            fig.set_size_inches((6, 4))
+        else:
+            fig = plot_projs_joint(
+                projs,
+                evoked=evoked,
+                picks_trace=picks_trace,
+                topomap_kwargs=topomap_kwargs,
+                show=False,
+            )
+
         self._add_figure(
             fig=fig,
             title=title,
@@ -3395,7 +3595,7 @@ def _add_inverse_operator(
         #         src=src
         #     )
         #     set_3d_view(fig, focalpoint=(0., 0., 0.06))
-        #     img = _fig_to_img(fig=fig, image_format=image_format)
+        #     img = self._fig_to_img(fig=fig, image_format=image_format)
 
         #     src_img_html = partial(
         #         _html_image_element,
@@ -3448,7 +3648,6 @@ def _add_evoked_joint(
                     )
                 )
 
-            _constrain_fig_resolution(fig, max_width=MAX_IMG_WIDTH, max_res=MAX_IMG_RES)
             title = f'Time course ({_handle_default("titles")[ch_type]})'
             self._add_figure(
                 fig=fig,
@@ -3473,7 +3672,6 @@ def _plot_one_evoked_topomap_timepoint(
             figsize=(2.5 * len(ch_types), 2),
             layout="constrained",
         )
-        _constrain_fig_resolution(fig, max_width=MAX_IMG_WIDTH, max_res=MAX_IMG_RES)
         ch_type_ax_map = dict(
             zip(
                 ch_types,
@@ -3492,12 +3690,11 @@ def _plot_one_evoked_topomap_timepoint(
             )
             ch_type_ax_map[ch_type][0].set_title(ch_type)
 
-        with BytesIO() as buff:
-            fig.savefig(buff, format="png", pad_inches=0)
-            plt.close(fig)
-            buff.seek(0)
-            fig_array = plt.imread(buff, format="png")
-        return fig_array
+        return self._fig_to_img(
+            fig=fig,
+            image_format="ndarray",
+            pad_inches=0,
+        )
 
     def _add_evoked_topomap_slider(
         self,
@@ -3620,7 +3817,6 @@ def _add_evoked_gfp(
             if idx < len(ch_types) - 1:
                 ax[idx].set_xlabel(None)
 
-        _constrain_fig_resolution(fig, max_width=MAX_IMG_WIDTH, max_res=MAX_IMG_RES)
         title = "Global field power"
         self._add_figure(
             fig=fig,
@@ -3638,7 +3834,6 @@ def _add_evoked_whitened(
     ):
         """Render whitened evoked."""
         fig = evoked.plot_white(noise_cov=noise_cov, show=False)
-        _constrain_fig_resolution(fig, max_width=MAX_IMG_WIDTH, max_res=MAX_IMG_RES)
         title = "Whitened"
 
         self._add_figure(
@@ -3763,7 +3958,6 @@ def _add_events(
             color=color,
             show=False,
         )
-        _constrain_fig_resolution(fig, max_width=MAX_IMG_WIDTH, max_res=MAX_IMG_RES)
         self._add_figure(
             fig=fig,
             title=title,
@@ -3813,7 +4007,6 @@ def _add_epochs_psd(self, *, epochs, psd, image_format, tags, section, replace):
                 fmax = np.inf
 
         fig = epochs_for_psd.compute_psd(fmax=fmax).plot(amplitude=False, show=False)
-        _constrain_fig_resolution(fig, max_width=MAX_IMG_WIDTH, max_res=MAX_IMG_RES)
         duration = round(epoch_duration * len(epochs_for_psd), 1)
         caption = (
             f"PSD calculated from {len(epochs_for_psd)} epochs ({duration:.1f} s)."
@@ -3836,6 +4029,7 @@ def _add_html_element(self, *, html, title, tags, section, replace, div_klass):
             tags=tags,
             title=title,
             html=html,
+            show=True,
         )
         self._add_or_replace(
             title=title,
@@ -3920,7 +4114,6 @@ def _add_epochs(
 
             assert len(figs) == 1
             fig = figs[0]
-            _constrain_fig_resolution(fig, max_width=MAX_IMG_WIDTH, max_res=MAX_IMG_RES)
             if ch_type in ("mag", "grad"):
                 title_start = "ERF image"
             else:
@@ -3964,9 +4157,6 @@ def _add_epochs(
                 fig = epochs.plot_drop_log(
                     subject=self.subject, ignore=drop_log_ignore, show=False
                 )
-                _constrain_fig_resolution(
-                    fig, max_width=MAX_IMG_WIDTH, max_res=MAX_IMG_RES
-                )
                 self._add_figure(
                     fig=fig,
                     image_format=image_format,
@@ -4010,7 +4200,6 @@ def _add_cov(self, *, cov, info, image_format, section, tags, replace):
         figs = [fig_cov, fig_svd]
         titles = ("Covariance matrix", "Singular values")
         for fig, title in zip(figs, titles):
-            _constrain_fig_resolution(fig, max_width=MAX_IMG_WIDTH, max_res=MAX_IMG_RES)
             self._add_figure(
                 fig=fig,
                 title=title,
@@ -4033,6 +4222,7 @@ def _add_trans(
         title,
         section,
         tags,
+        coord_frame,
         replace,
     ):
         """Render trans (only PNG)."""
@@ -4049,10 +4239,14 @@ def _add_trans(
             dig=True,
             meg=["helmet", "sensors"],
             show_axes=True,
-            coord_frame="mri",
+            coord_frame=coord_frame,
         )
         img, caption = _iterate_trans_views(
-            function=plot_alignment, alpha=alpha, **kwargs
+            function=plot_alignment,
+            alpha=alpha,
+            max_width=self.img_max_width,
+            max_res=self.img_max_res,
+            **kwargs,
         )
         self._add_image(
             img=img,
@@ -4143,7 +4337,9 @@ def _add_stc(
                     ax.imshow(brain.screenshot(time_viewer=True, mode="rgb"))
                     ax.axis("off")
                     _constrain_fig_resolution(
-                        fig, max_width=stc_plot_kwargs["size"][0], max_res=MAX_IMG_RES
+                        fig,
+                        max_width=stc_plot_kwargs["size"][0],
+                        max_res=self.img_max_res,
                     )
                     figs.append(fig)
                     plt.close(fig)
@@ -4172,12 +4368,12 @@ def _add_stc(
                     _constrain_fig_resolution(
                         fig_lh,
                         max_width=stc_plot_kwargs["size"][0],
-                        max_res=MAX_IMG_RES,
+                        max_res=self.img_max_res,
                     )
                     _constrain_fig_resolution(
                         fig_rh,
                         max_width=stc_plot_kwargs["size"][0],
-                        max_res=MAX_IMG_RES,
+                        max_res=self.img_max_res,
                     )
                     figs.append(brain_lh)
                     figs.append(brain_rh)
@@ -4201,7 +4397,10 @@ def _add_stc(
             section=section,
             tags=tags,
             replace=replace,
+            own_figure=False,  # prevent rescaling
         )
+        for fig in figs:
+            plt.close(fig)
 
     def _add_bem(
         self,
@@ -4214,6 +4413,7 @@ def _add_bem(
         image_format,
         title,
         tags,
+        section,
         replace,
     ):
         """Render mri+bem (only PNG)."""
@@ -4263,7 +4463,7 @@ def _add_bem(
         )
         self._add_or_replace(
             title=title,
-            section=None,  # no nesting
+            section=section,
             tags=tags,
             html_partial=html_partial,
             replace=replace,
diff --git a/mne/report/tests/test_report.py b/mne/report/tests/test_report.py
index 6e76c54e6c2..66f4cd9e336 100644
--- a/mne/report/tests/test_report.py
+++ b/mne/report/tests/test_report.py
@@ -593,7 +593,8 @@ def test_validate_input():
 
 def test_open_report(tmp_path):
     """Test the open_report function."""
-    pytest.importorskip("h5io")
+    h5py = pytest.importorskip("h5py")
+    h5io = pytest.importorskip("h5io")
     hdf5 = str(tmp_path / "report.h5")
 
     # Test creating a new report through the open_report function
@@ -605,6 +606,11 @@ def test_open_report(tmp_path):
     # Exiting the context block should have triggered saving to HDF5
     assert Path(hdf5).exists()
 
+    # Let's add some companion data to the HDF5 file
+    with h5py.File(hdf5, "r+") as f:
+        h5io.write_hdf5(f, "test", title="companion")
+    assert h5io.read_hdf5(hdf5, title="companion") == "test"
+
     # Load the HDF5 version of the report and check equivalence
     report2 = open_report(hdf5)
     assert report2.fname == str(hdf5)
@@ -621,8 +627,12 @@ def test_open_report(tmp_path):
     # Check that the context manager doesn't swallow exceptions
     with pytest.raises(ZeroDivisionError):
         with open_report(hdf5, subjects_dir=str(tmp_path)) as report:
+            assert h5io.read_hdf5(hdf5, title="companion") == "test"
             1 / 0
 
+    # Check that our companion data survived
+    assert h5io.read_hdf5(hdf5, title="companion") == "test"
+
 
 def test_remove():
     """Test removing figures from a report."""
@@ -1068,6 +1078,73 @@ def test_manual_report_2d(tmp_path, invisible_fig):
     r.save(fname=fname, open_browser=False)
 
 
+def test_report_tweaks(tmp_path, monkeypatch):
+    """Test tweaking of report params."""
+    r = Report(image_format="png")
+    assert r.collapse == ()
+    assert r.img_max_width == 850
+    assert r.img_max_res == 100
+
+    events = np.array([[0, 0, 1], [1, 0, 2], [2, 0, 3]])
+    kwargs = dict(events=events, sfreq=1000.0, title="my events", section="my section")
+    with plt.rc_context(rc={"figure.dpi": 200, "figure.figsize": (10, 10)}):
+        r.add_events(**kwargs)
+
+    fname = tmp_path / "report.html"
+    r.save(fname, open_browser=False)
+
+    html = fname.read_text(encoding="utf-8")
+    assert html.count("collapse show") == 2, fname  # section and element
+
+    r.collapse = ["section"]
+    r.save(fname, open_browser=False, overwrite=True)
+    html = fname.read_text(encoding="utf-8")
+    assert html.count("collapse show") == 1, fname  # section collapsed
+
+    # Bad input handling
+    with pytest.raises(ValueError):
+        r.collapse = "foo"
+    with pytest.raises(TypeError):
+        r.collapse = 1
+    with pytest.raises(TypeError):
+        r.img_max_width = "foo"
+    with pytest.raises(ValueError):
+        r.img_max_width = -1
+    with pytest.raises(TypeError):
+        r.img_max_res = "foo"
+    with pytest.raises(ValueError):
+        r.img_max_res = -1
+
+    # Figure out the size of our rendered image (max width 850)
+    img_re = re.compile(r'src="data:image/png;base64([^"]+)"')
+    imgs = img_re.findall(html)
+    assert len(imgs) == 2  # the first is our logo
+    img = plt.imread(BytesIO(base64.b64decode(imgs[1].encode("ascii"))))
+    assert img.shape == (850, 850, 3)
+
+    # Now let's limit it by max resolution (100 dpi)
+    r = Report(image_format="png")
+    r.img_max_width = None
+    with plt.rc_context(rc={"figure.dpi": 200, "figure.figsize": (10, 10)}):
+        r.add_events(**kwargs)
+    r.save(fname, open_browser=False, overwrite=True)
+    imgs = img_re.findall(fname.read_text(encoding="utf-8"))
+    assert len(imgs) == 2
+    img = plt.imread(BytesIO(base64.b64decode(imgs[1].encode("ascii"))))
+    assert img.shape == (1000, 1000, 3)  # figure.figsize * Report.img_max_res
+
+    # Now let's do unconstrained
+    r = Report(image_format="png")
+    r.img_max_width = r.img_max_res = None
+    with plt.rc_context(rc={"figure.dpi": 200, "figure.figsize": (10, 10)}):
+        r.add_events(**kwargs)
+    r.save(fname, open_browser=False, overwrite=True)
+    imgs = img_re.findall(fname.read_text(encoding="utf-8"))
+    assert len(imgs) == 2
+    img = plt.imread(BytesIO(base64.b64decode(imgs[1].encode("ascii"))))
+    assert img.shape == (2000, 2000, 3)  # figure.figsize * figure.dpi
+
+
 @pytest.mark.slowtest  # 30 s on Azure
 @testing.requires_testing_data
 def test_manual_report_3d(tmp_path, renderer):
diff --git a/mne/utils/docs.py b/mne/utils/docs.py
index 4dec335df1f..969ec347f0e 100644
--- a/mne/utils/docs.py
+++ b/mne/utils/docs.py
@@ -1118,14 +1118,20 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75):
 """
 
 docdict["destination_maxwell_dest"] = """
-destination : path-like | array-like, shape (3,) | None
-    The destination location for the head. Can be ``None``, which
-    will not change the head position, or a path to a FIF file
-    containing a MEG device<->head transformation, or a 3-element array
-    giving the coordinates to translate to (with no rotations).
-    For example, ``destination=(0, 0, 0.04)`` would translate the bases
-    as ``--trans default`` would in MaxFilter™ (i.e., to the default
-    head location).
+destination : path-like | array-like, shape (3,) | instance of Transform | None
+    The destination location for the head. Can be:
+
+    ``None``
+      Will not change the head position.
+    :class:`~mne.transforms.Transform`
+      A MEG device<->head transformation, e.g. ``info["dev_head_t"]``.
+    :class:`numpy.ndarray`
+      A 3-element array giving the coordinates to translate to (with no rotations).
+      For example, ``destination=(0, 0, 0.04)`` would translate the bases
+      as ``--trans default`` would in MaxFilter™ (i.e., to the default
+      head location).
+    ``path-like``
+      A path to a FIF file containing the destination MEG device<->head transformation.
 """
 
 docdict["detrend_epochs"] = """
diff --git a/mne/viz/_3d.py b/mne/viz/_3d.py
index 2fb94134830..7f8fb98b07a 100644
--- a/mne/viz/_3d.py
+++ b/mne/viz/_3d.py
@@ -50,6 +50,8 @@
 )
 from ..transforms import (
     Transform,
+    _angle_between_quats,
+    _angle_dist_between_rigid,
     _ensure_trans,
     _find_trans,
     _frame_to_str,
@@ -131,6 +133,7 @@ def plot_head_positions(
     info=None,
     color="k",
     axes=None,
+    totals=False,
 ):
     """Plot head positions.
 
@@ -149,10 +152,9 @@ def plot_head_positions(
         directional axes in "field" mode.
     show : bool
         Show figure if True. Defaults to True.
-    destination : str | array-like, shape (3,) | None
-        The destination location for the head, assumed to be in head
-        coordinates. See :func:`mne.preprocessing.maxwell_filter` for
-        details.
+    destination : path-like | array-like, shape (3,) | instance of Transform | None
+        The destination location for the head. See
+        :func:`mne.preprocessing.maxwell_filter` for details.
 
         .. versionadded:: 0.16
     %(info)s If provided, will be used to show the destination position when
@@ -164,12 +166,16 @@ def plot_head_positions(
         arrows in ``mode == 'field'``.
 
         .. versionadded:: 0.16
-    axes : array-like, shape (3, 2)
+    axes : array-like, shape (3, 2) or (4, 2)
         The matplotlib axes to use.
 
         .. versionadded:: 0.16
         .. versionchanged:: 1.8
            Added support for making use of this argument when ``mode="field"``.
+    totals : bool
+        If True and in traces mode, show the total distance and angle in a fourth row.
+
+        .. versionadded:: 1.9
 
     Returns
     -------
@@ -182,12 +188,12 @@ def plot_head_positions(
     from ..preprocessing.maxwell import _check_destination
 
     _check_option("mode", mode, ["traces", "field"])
+    _validate_type(totals, bool, "totals")
     dest_info = dict(dev_head_t=None) if info is None else info
     destination = _check_destination(destination, dest_info, head_frame=True)
     if destination is not None:
         destination = _ensure_trans(destination, "head", "meg")  # probably inv
-        destination = destination["trans"][:3].copy()
-        destination[:, 3] *= 1000
+        destination = destination["trans"]
 
     if not isinstance(pos, list | tuple):
         pos = [pos]
@@ -228,15 +234,17 @@ def plot_head_positions(
                 surf["rr"] *= 1000.0
     helmet_color = DEFAULTS["coreg"]["helmet_color"]
     if mode == "traces":
+        want_shape = (3 + int(totals), 2)
         if axes is None:
-            axes = plt.subplots(3, 2, sharex=True)[1]
+            _, axes = plt.subplots(*want_shape, sharex=True, layout="constrained")
         else:
             axes = np.array(axes)
-        if axes.shape != (3, 2):
-            raise ValueError(f"axes must have shape (3, 2), got {axes.shape}")
+        _check_option("axes.shape", axes.shape, (want_shape,))
         fig = axes[0, 0].figure
-
-        labels = ["xyz", ("$q_1$", "$q_2$", "$q_3$")]
+        labels = [["x (mm)", "y (mm)", "z (mm)"], ["$q_1$", "$q_2$", "$q_3$"]]
+        if totals:
+            labels[0].append("dist (mm)")
+            labels[1].append("angle (°)")
         for ii, (quat, coord) in enumerate(zip(use_quats.T, use_trans.T)):
             axes[ii, 0].plot(t, coord, color, lw=1.0, zorder=3)
             axes[ii, 0].set(ylabel=labels[0][ii], xlim=t[[0, -1]])
@@ -245,9 +253,19 @@ def plot_head_positions(
             for b in borders[:-1]:
                 for jj in range(2):
                     axes[ii, jj].axvline(t[b], color="r")
-        for ii, title in enumerate(("Position (mm)", "Rotation (quat)")):
-            axes[0, ii].set(title=title)
-            axes[-1, ii].set(xlabel="Time (s)")
+        if totals:
+            vals = [
+                np.linalg.norm(use_trans, axis=-1),
+                np.rad2deg(_angle_between_quats(use_quats)),
+            ]
+            ii = -1
+            for ci, val in enumerate(vals):
+                axes[ii, ci].plot(t, val, color, lw=1.0, zorder=3)
+                axes[ii, ci].set(ylabel=labels[ci][ii], xlim=t[[0, -1]])
+        titles = ["Position", "Rotation"]
+        for ci, title in enumerate(titles):
+            axes[0, ci].set(title=title)
+            axes[-1, ci].set(xlabel="Time (s)")
         if rrs is not None:
             pos_bads = np.any(
                 [
@@ -305,10 +323,18 @@ def plot_head_positions(
 
         if destination is not None:
             vals = np.array(
-                [destination[:, 3], rot_to_quat(destination[:, :3])]
+                [1000 * destination[:3, 3], rot_to_quat(destination[:3, :3])]
             ).T.ravel()
-            for ax, val in zip(fig.axes, vals):
+            for ax, val in zip(axes[:3].ravel(), vals):
                 ax.axhline(val, color="r", ls=":", zorder=2, lw=1.0)
+            if totals:
+                dest_ang, dest_dist = _angle_dist_between_rigid(
+                    destination,
+                    angle_units="deg",
+                    distance_units="mm",
+                )
+                axes[-1, 0].axhline(dest_dist, color="r", ls=":", zorder=2, lw=1.0)
+                axes[-1, 1].axhline(dest_ang, color="r", ls=":", zorder=2, lw=1.0)
 
     else:  # mode == 'field':
         from matplotlib.colors import Normalize
diff --git a/mne/viz/tests/test_3d.py b/mne/viz/tests/test_3d.py
index 9c398f94dec..6f109b9490b 100644
--- a/mne/viz/tests/test_3d.py
+++ b/mne/viz/tests/test_3d.py
@@ -99,9 +99,11 @@ def test_plot_head_positions():
     pos = np.random.RandomState(0).randn(4, 10)
     pos[:, 0] = np.arange(len(pos))
     destination = (0.0, 0.0, 0.04)
-    plot_head_positions(pos)
+    fig = plot_head_positions(pos)
+    assert len(fig.axes) == 6
     plot_head_positions(pos, mode="field", info=info, destination=destination)
-    plot_head_positions([pos, pos])  # list support
+    fig = plot_head_positions([pos, pos], totals=True)  # list and totals support
+    assert len(fig.axes) == 8
     fig, ax = plt.subplots()
     with pytest.raises(TypeError, match="instance of Axes3D"):
         plot_head_positions(pos, mode="field", info=info, axes=ax)
diff --git a/tutorials/intro/70_report.py b/tutorials/intro/70_report.py
index fbce79c6324..d23bd54aebf 100644
--- a/tutorials/intro/70_report.py
+++ b/tutorials/intro/70_report.py
@@ -184,8 +184,26 @@
 ecg_proj_path = sample_dir / "sample_audvis_ecg-proj.fif"
 report = mne.Report(title="Projectors example")
 report.add_projs(info=raw_path, title="Projs from info")
-report.add_projs(info=raw_path, projs=ecg_proj_path, title="ECG projs from path")
+
+# Now a joint plot
+events = mne.read_events(sample_dir / "sample_audvis_ecg-eve.fif")
+raw_full = mne.io.read_raw(sample_dir / "sample_audvis_raw.fif").crop(0, 60).load_data()
+ecg_evoked = mne.Epochs(
+    raw=raw_full,
+    events=events,
+    tmin=-0.5,
+    tmax=0.5,
+    baseline=(None, None),
+).average()
+report.img_max_width = None  # do not constrain image width
+report.add_projs(
+    info=ecg_evoked,
+    projs=ecg_proj_path,
+    title="ECG projs from path",
+    joint=True,  # use joint version of the plot
+)
 report.save("report_projs.html", overwrite=True)
+del raw_full, events, ecg_evoked
 
 # %%
 # Adding `~mne.preprocessing.ICA`
diff --git a/tutorials/preprocessing/59_head_positions.py b/tutorials/preprocessing/59_head_positions.py
index 37ed574132b..4085c4792b6 100644
--- a/tutorials/preprocessing/59_head_positions.py
+++ b/tutorials/preprocessing/59_head_positions.py
@@ -77,7 +77,7 @@
 
 # sphinx_gallery_thumbnail_number = 2
 
-mne.viz.plot_head_positions(head_pos, mode="traces")
+mne.viz.plot_head_positions(head_pos, mode="traces", totals=True)
 
 # %%
 # Or we can visualize them as a continuous field (with the vectors pointing