Interactive Operations and Region of Interest (ROI)
Interactive operations
The function interactive() simplifies the definition of
operations that are automatically updated when an event is triggered. By
default the operation is recomputed when the data or the axes of the original
signal is changed.
>>> s = hs.signals.Signal1D(np.arange(10.))
>>> ssum = hs.interactive(s.sum, axis=0)
>>> ssum.data
array([45.0])
>>> s.data /= 10
>>> s.events.data_changed.trigger(s)
>>> ssum.data
array([ 4.5])
Interactive operations can be performed in a chain.
>>> s = hs.signals.Signal1D(np.arange(2 * 3 * 4).reshape((2, 3, 4)))
>>> ssum = hs.interactive(s.sum, axis=0)
>>> ssum_mean = hs.interactive(ssum.mean, axis=0)
>>> ssum_mean.data
array([ 30., 33., 36., 39.])
>>> s.data
array([[[ 0, 1, 2, 3],
[ 4, 5, 6, 7],
[ 8, 9, 10, 11]],
[[12, 13, 14, 15],
[16, 17, 18, 19],
[20, 21, 22, 23]]])
>>> s.data *= 10
>>> s.events.data_changed.trigger(obj=s)
>>> ssum_mean.data
array([ 300., 330., 360., 390.])
Region Of Interest (ROI)
ROIs can be defined to select part of any compatible signal and may be applied either to the navigation or to the signal axes. A number of different ROIs are available:
Once created, an ROI can be applied to the signal:
>>> s = hs.signals.Signal1D(np.arange(2000).reshape((20,10,10)))
>>> im = hs.signals.Signal2D(np.arange(100).reshape((10,10)))
>>> roi = hs.roi.RectangularROI(left=3, right=7, top=2, bottom=5)
>>> sr = roi(s)
>>> sr
<Signal1D, title: , dimensions: (4, 3|10)>
>>> imr = roi(im)
>>> imr
<Signal2D, title: , dimensions: (|4, 3)>
ROIs can also be used interactively with widgets.
The following example shows how to interactively apply ROIs to an image. Note
that it is necessary to plot the signal onto which the widgets will be
added before calling interactive().
>>> import scipy.misc
>>> im = hs.signals.Signal2D(scipy.misc.ascent())
>>> rectangular_roi = hs.roi.RectangularROI(left=30, right=500,
... top=200, bottom=400)
>>> line_roi = hs.roi.Line2DROI(0, 0, 512, 512, 1)
>>> point_roi = hs.roi.Point2DROI(256, 256)
>>> im.plot()
>>> roi2D = rectangular_roi.interactive(im, color="blue")
>>> roi1D = line_roi.interactive(im, color="yellow")
>>> roi0D = point_roi.interactive(im, color="red")
Note
Depending on your screen and display settings, it can be difficult to pick or manipulate widgets and you can try to change the pick tolerance in the HyperSpy plot preferences. Typically, using a 4K resolution with a small scaling factor (<150 %), setting the pick tolerance to 15 instead of 7.5 makes the widgets easier to manipulate.
Notably, since ROIs are independent from the signals they sub-select, the widget can be plotted on a different signal altogether.
>>> import scipy.misc
>>> im = hs.signals.Signal2D(scipy.misc.ascent())
>>> s = hs.signals.Signal1D(np.random.rand(512, 512, 512))
>>> roi = hs.roi.RectangularROI(left=30, right=77, top=20, bottom=50)
>>> s.plot() # plot signal to have where to display the widget
>>> imr = roi.interactive(im, navigation_signal=s, color="red")
>>> roi(im).plot()
ROIs are implemented in terms of physical coordinates and not pixels, so with proper calibration will always point to the same region.
And of course, as all interactive operations, interactive ROIs are chainable. The following example shows how to display interactively the histogram of a rectangular ROI. Notice how we customise the default event connections in order to increase responsiveness.
>>> import scipy.misc
>>> im = hs.signals.Signal2D(scipy.misc.ascent())
>>> im.plot()
>>> roi = hs.roi.RectangularROI(left=30, right=500, top=200, bottom=400)
>>> im_roi = roi.interactive(im, color="red")
>>> roi_hist = hs.interactive(im_roi.get_histogram,
... event=roi.events.changed,
bins=150, # Set number of bins for `get_histogram`
... recompute_out_event=None)
>>> roi_hist.plot()
New in version 1.3: ROIs can be used in place of slices when indexing and to define a
signal range in functions taken a signal_range argument.
All ROIs have a gui() method that displays an user interface if
a hyperspy GUI is installed (currently only works with the
hyperspy_gui_ipywidgets GUI), enabling precise control of the ROI
parameters:
>>> # continuing from above:
>>> roi.gui()
New in version 1.4: angle() can be used to calculate an angle between
ROI line and one of the axes providing its name through optional argument axis:
>>> import scipy
>>> holo = hs.datasets.example_signals.object_hologram()
>>> roi = hs.roi.Line2DROI(x1=465.577, y1=445.15, x2=169.4, y2=387.731, linewidth=0)
>>> holo.plot()
>>> ss = roi.interactive(holo)
>>> roi.angle(axis='y')
-100.97166759025453
The default output of the method is in degrees, though radians can be selected as follows:
>>> roi.angle(axis='vertical', units='radians')
-1.7622880506791903
Conveniently, angle() can be used to rotate an image to
align selected features with respect to vertical or horizontal axis:
>>> holo.map(scipy.ndimage.rotate, angle=roi.angle(axis='horizontal'), inplace=False).plot()
Slicing using ROIs
ROIs can be used in place of slices when indexing. For example:
>>> s = hs.datasets.example_signals.EDS_TEM_Spectrum()
>>> roi = hs.roi.SpanROI(left=5, right=15)
>>> sc = s.isig[roi]
>>> im = hs.datasets.example_signals.object_hologram()
>>> roi = hs.roi.RectangularROI(left=120, right=460., top=300, bottom=560)
>>> imc = im.isig[roi]
New in version 1.3: gui() method.
New in version 1.6: New __getitem__() method for all ROIs.
In addition the following all ROIs have a py:meth:__getitem__ method that enables
using them in place of tuples.
For example, the method align2D() takes a roi
argument with the left, right, top, bottom coordinates of the ROI.
Handily, we can pass a RectangularROI ROI instead.
>>> import hyperspy.api as hs
>>> import numpy as np
>>> im = hs.signals.Signal2D(np.random.random((10,30,30))
>>> roi = hs.roi.RectangularROI(left=2, right=10, top=0, bottom=5))
>>> tuple(roi)
(2.0, 10.0, 0.0, 5.0)
>>> im.align2D(roi=roi)