Merge pull request #3227 from jlaehne/example-line-profile

Add example on extracting line profiles

.github/workflows/doc.yml

@@ -10,4 +10,5 @@ jobs:
       # install with speed extra to avoid warnings
       pip_extra_doc: 'doc,speed'
       # graphviz is required to build mermaid graph
-      install_package_ubuntu: graphviz
+      # optipng is required to optimize thumbnail
+      install_package_ubuntu: graphviz optipng

.gitignore

@@ -1,54 +1,55 @@
 syntax: glob
-.spyderworkspace
-.coverage
-/MANIFEST
-.hook_ignore*
-*.so
-*.pyc
-*.pyd
-*.swp
 *~
 *.bak
+*.deb
 *.mex
+*nbc
+*nbi
 *.o
-dist
-*.deb
+*.pyc
+*.pyd
+*.pyproj
+*.so
 *.swo
+*.swp
+*.DS_Store
+*__pycache__
+*Thumbs.db
+/.cache/
+/.spyproject/
+.coverage
+.hook_ignore*
+.idea/*
+.python-version
+.ropeproject/*
+.spyderproject
+.spyderworkspace
+~.vimrc
+desktop.ini
+dist
+/MANIFEST
 build/*
 bin/*.bat
 PortableInstall/*
 hyperspy.egg-info/*
-deb_dist/*
-~.vimrc
 data/octave-core
-.spyderproject
+deb_dist/*
 doc/_build/*
 doc/.build/*
 doc/api/*
-doc/user_guide/_build/*
-doc/user_guide/.build/*
-setup/windows/requires/*
-setup/windows/reccomends/*
 doc/auto_examples
-examples/io/*.msa
 doc/gh-pages
 doc/log.txt
-*Thumbs.db
-*.DS_Store
-.ropeproject/*
-.idea/*
-desktop.ini
-*.pyproj
-hyperspy/tests/misc/cython/test_cython_integration.c
+doc/user_guide/_build/*
+doc/user_guide/.build/*
+examples/io/*.msa
+examples/region_of_interest/*.msa
 hyperspy/io_plugins/unbcf_fast.c
 hyperspy/misc/etc/test_compilers.obj
-/.cache/
-/.spyproject/
-*nbc
-*nbi
 hyperspy/tests/io/edax_files.zip
-.python-version
-*__pycache__
+hyperspy/tests/misc/cython/test_cython_integration.c
+setup/windows/requires/*
+setup/windows/reccomends/*
 
 ### Code ###
 # Visual Studio Code - https://code.visualstudio.com/

CHANGES.rst

@@ -4,7 +4,7 @@ Changelog
 *********
 
 Changelog entries for the development version are available at
-https://hyperspy.readthedocs.io/en/latest/user_guide/changes.html
+https://hyperspy.readthedocs.io/en/latest/changes.html
 
 .. towncrier-draft-entries:: |release| [UNRELEASED]
 
@@ -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/install.rst

@@ -145,7 +145,7 @@ To learn more about the Anaconda eco-system:
 
 - Choose between `Anaconda or Miniconda <https://docs.conda.io/projects/conda/en/latest/user-guide/install/download.html#anaconda-or-miniconda>`_?
 - Understanding `conda and pip <https://www.anaconda.com/blog/understanding-conda-and-pip>`_.
-- What is `conda-forge <https://conda-forge.org/#about>`__.
+- What is `conda-forge <https://conda-forge.org>`__.
 
 .. _install-with-pip:
 

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/README.rst

@@ -3,4 +3,5 @@
 Gallery of Examples
 ===================
 
-Below is a gallery of examples.
+This gallery contains the commented code for short examples illustrating simple
+tasks that can be performed with HyperSpy.

examples/model_fitting/plot_residual.py

@@ -31,6 +31,6 @@
 #%%
 # Plot the fitted model with residual:
 m.plot(plot_residual=True)
-
-#%%
+# Choose the second figure as gallery thumbnail:
 # sphinx_gallery_thumbnail_number = 2
+

examples/region_of_interest/ExtractLineProfile.py

@@ -0,0 +1,64 @@
+"""
+Extract line profile from image interactively
+=============================================
+
+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.
+
+"""
+
+#%%
+#.. 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.
+
+#%%
+# 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()
+
+#%%
+# 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)
+
+#%%
+# Extract data along the ROI as new signal by "slicing" the signal and plot the
+# profile:
+profile = line_roi(im0)
+profile.plot()
+
+#%%
+# 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')
+
+#%%
+# 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))
+
+#%%
+# 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
+
+#%%
+# 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",

upcoming_changes/3227.enhancements.rst

@@ -0,0 +1 @@
+Add an example to the gallery to show how to extract a line profile from an image using a Line2DROI