merge with user guide example

CHANGES.rst

@@ -899,7 +899,7 @@ Enhancements
   See :ref:`model.multidimensional-label`.
 * The :py:func:`~.api.plot.plot_spectra`  function now listens to
   events to update the figure automatically.
-  See :ref:`this example <plot_profiles_interactive-label>`.
+  See :ref:`this example <sphx_glr_auto_examples_region_of_interest_ExtractLineProfile.py>`.
 * Improve thread-based parallelism. Add ``max_workers`` argument to the
   :py:meth:`~.api.signals.BaseSignal.map` method, such that the user can directly
   control how many threads they launch.

doc/conf.py

@@ -396,6 +396,9 @@
     'gallery_dirs': 'auto_examples',  # path to where to save gallery generated output
     'filename_pattern': '.py',        # pattern to define which will be executed
     'ignore_pattern': '_sgskip.py',   # pattern to define which will not be executed
+    'compress_images': ('images', 'thumbnails'), # use optipng to reduce image file size
+    'notebook_images': 'https://hyperspy.org/hyperspy-doc/current/', # folder for loading images in gallery
+    "reference_url": {"hyperspy": None},
 }
 
 graphviz_output_format = "svg"
@@ -410,4 +413,4 @@
 def setup(app):
     app.add_css_file("custom-styles.css")
 
-tls_verify = False
+tls_verify = False

doc/user_guide/visualisation.rst

@@ -1021,38 +1021,6 @@ and "overlap" styles:
   Plotting on existing matplotlib axes.
 
 
-.. _plot_profiles_interactive-label:
-
-Plotting profiles interactively
--------------------------------
-
-Spectra or line profile can be plotted interactively on the same figure using
-the :func:`~.api.plot.plot_spectra` function. For example, profiles
-obtained from different Signal2D using the :class:`~.roi.Line2DROI` ROI can
-be plotted interactively:
-
-.. code-block:: python
-
-    >>> import holospy as  # doctest: +SKIP
-    >>> im0 = holo.data.Fe_needle_reference_hologram() # doctest: +SKIP
-    >>> im1 = holo.data.Fe_needle_hologram() # doctest: +SKIP
-    >>> im0.plot() # doctest: +SKIP
-    >>> im1.plot() # doctest: +SKIP
-    >>> # Create the ROI
-    >>> line_profile = hs.roi.Line2DROI(400, 250, 220, 600) # doctest: +SKIP
-    >>> # Obtain the signals to plot by "slicing" the signals with the ROI
-    >>> line0 = line_profile.interactive(im0) # doctest: +SKIP
-    >>> line1 = line_profile.interactive(im1) # doctest: +SKIP
-    >>> # Plotting the profile on the same figure
-    >>> hs.plot.plot_spectra([line0, line1]) # doctest: +SKIP
-
-.. figure::  images/interactive_profiles.gif
-  :align:   center
-  :width:   1024
-
-  Plotting profiles from different images interactively.
-
-
 .. _plot.signals:
 
 Plotting several signals

examples/region_of_interest/ExtractLineProfile.py

@@ -1,57 +1,64 @@
 """
-Extract line profile from image
-===============================
+Extract line profile from image interactively
+=============================================
 
-Use a ``Line2DROI`` to interactively extract a line profile with a certain width
-from an image.
+Interactively extract a line profile (with a certain width) from an image using
+:py:class:`~.api.roi.Line2DROI`. Use :func:`~.api.plot.plot_spectra` to plot several
+line profiles on the same figure. Save a profile data as ``msa`` file.
 
 """
 
 #%%
-# Initialize image data as HyperSpy signal:
-import hyperspy.api as hs
-import scipy
-img = hs.signals.Signal2D(scipy.datasets.ascent())
-
-#%%
-# Intialize Line-ROI from pixel (90,90) to pixel (200,250) of width 5.
-# You can also use calibrated axes units by providing floats instead of integers.
-line_roi = hs.roi.Line2DROI(90, 90, 200, 250, 5)
+#.. figure::  ../../_static/interactive_profiles.gif
+#    :align:   center
+#    :width:   1024
+#    :alt:     Interactive example gif of region of interest and associated profile plots.
+#
+#    Extracting line profiles and interactive plotting.
 
 #%%
-# Plot the image and display the ROI (creates new signal object):
-img.plot(cmap='viridis')
-roi1D = line_roi.interactive(img, color='yellow')
+# Initialize image data as HyperSpy signal:
+import hyperspy.api as hs
+import holospy as holo
+im0 = holo.data.Fe_needle_reference_hologram()
+im1 = holo.data.Fe_needle_hologram()
 
 #%%
-# You can drag and drop the ends of the ROI to adjust.
-# Print the (updated) parameters of the ROI:
-print('%.3f, %.3f, %.3f, %.3f, %.2f' % (line_roi.x1, line_roi.y1, line_roi.x2, line_roi.y2, line_roi.linewidth))
+# Intialize Line-ROI from position (400,250) to position (220,600) of width 5
+# in calibrated axes units (in the current example equal to the image pixels):
+line_roi = hs.roi.Line2DROI(400, 250, 220, 600, 5)
 
 #%%
-# You can also display the same ROI on a second image
-# (e.g. to make sure that a profile is well placed on both images).
-# In this example, we create a second image by differentiating the original image:
-img2 = img.diff(axis=-1)
-img2.plot()
-roi1D = line_roi.interactive(img2, color='green')
+# Extract data along the ROI as new signal by "slicing" the signal and plot the
+# profile:
+profile = line_roi(im0)
+profile.plot()
 
 #%%
-# Extract data along ROI as new signal:
-profile = line_roi(img)
-profile
+# Slicing of the signal is not interactive. If you want to modify the line along
+# which the profile is extracted, you can plot the image and display the ROI 
+# interactively (creates a new signal object). You can even display the same ROI
+# on a second image to make sure that a profile is well placed on both images:
+im0.plot()
+profile1 = line_roi.interactive(im0, color='green')
+im1.plot()
+profile2 = line_roi.interactive(im1, color='green')
 
 #%%
-# Plot the profile:
-profile.plot()
+# You can then drag and drop the ends of the ROI to adjust the placement.
+#
+# If you want to later update the ROI initialization with the modified parameters,
+# you can print these:
+print(tuple(line_roi))
 
 #%%
-# Extract data along the same ROI from the second image and plot both profiles:
-profile2 = line_roi(img2)
-hs.plot.plot_spectra([profile, profile2])
-# Choose the third figure as gallery thumbnail:
+# You can now directly access the data of the profile objects, e.g. to plot both
+# profiles in a single plot:
+hs.plot.plot_spectra([profile1, profile2])
+# Choose the fourth figure as gallery thumbnail:
 # sphinx_gallery_thumbnail_number = 4
 
 #%%
-# Save profile as `.msa` text file:
-profile.save('extracted-line-profile.msa', format='XY')
+# Since the profile is a signal object, you can use any other functionality provided
+# by hyperspy, e.g. to save a profile as `.msa` text file:
+profile1.save('extracted-line-profile.msa', format='XY')

pyproject.toml

@@ -106,6 +106,7 @@ dev = [
     "hyperspy[tests]",
 ]
 doc = [
+    "holospy", # example gallery
     "IPython", # Needed in testing code in basic_usage.rst
     "numpydoc",
     "pydata_sphinx_theme",