hyperspy.roi module

Region of interests (ROIs).

ROIs operate on BaseSignal instances and include widgets for interactive operation.

The following 1D ROIs are available:

Point1DROI

Single element ROI of a 1D signal.

SpanROI

Interval ROI of a 1D signal.

The following 2D ROIs are available:

Point2DROI

Single element ROI of a 2D signal.

RectangularROI

Rectagular ROI of a 2D signal.

CircleROI

(Hollow) circular ROI of a 2D signal

Line2DROI

Line profile of a 2D signal with customisable width.

class hyperspy.roi.BaseInteractiveROI

Bases: hyperspy.roi.BaseROI

Base class for interactive ROIs, i.e. ROIs with widget interaction. The base class defines a lot of the common code for interacting with widgets, but inhertors need to implement the following functions:

_get_widget_type() _apply_roi2widget(widget) _set_from_widget(widget)

add_widget(signal, axes=None, widget=None, color='green', **kwargs)

Add a widget to visually represent the ROI, and connect it so any changes in either are reflected in the other. Note that only one widget can be added per signal/axes combination.

signalSignal

The signal to witch the widget is added. This is used to determine with plot to add the widget to, and it supplies the axes_manager for the widget.

axesspecification of axes to use, default = None

The axes argument specifies which axes the ROI will be applied on. The DataAxis in the collection can be either of the following:

  • a tuple of:

    • DataAxis. These will not be checked with signal.axes_manager.

    • anything that will index signal.axes_manager

  • For any other value, it will check whether the navigation space can fit the right number of axis, and use that if it fits. If not, it will try the signal space.

widgetWidget or None (default)

If specified, this is the widget that will be added. If None, the default widget will be used, as given by _get_widget_type().

colorMatplotlib color specifier (default: ‘green’)

The color for the widget. Any format that matplotlib uses should be ok. This will not change the color fo any widget passed with the ‘widget’ argument.

kwargs:

All keyword argument are passed to the widget constructor.

interactive(signal, navigation_signal='same', out=None, color='green', **kwargs)

Creates an interactively sliced Signal (sliced by this ROI) via hyperspy.interactive.

signalSignal

The source signal to slice

navigation_signalSignal, None or “same” (default)

If not None, it will automatically create a widget on navigation_signal. Passing “same” is identical to passing the same signal to ‘signal’ and ‘navigation_signal’, but is less ambigous, and allows “same” to be the default value.

outSignal

If not None, it will use ‘out’ as the output instead of returning a new Signal.

colorMatplotlib color specifier (default: ‘green’)

The color for the widget. Any format that matplotlib uses should be ok. This will not change the color fo any widget passed with the ‘widget’ argument.

**kwargs

All kwargs are passed to the roi __call__ method which is called interactively on any roi attribute change.

remove_widget(signal)
update()

Function responsible for updating anything that depends on the ROI. It should be called by implementors whenever the ROI changes. This implementation updates the widgets associated with it, and triggers the changed event.

class hyperspy.roi.BasePointROI

Bases: hyperspy.roi.BaseInteractiveROI

Base ROI class for point ROIs, i.e. ROIs with a unit size in each of its dimensions.

class hyperspy.roi.BaseROI

Bases: traits.has_traits.HasTraits

Base class for all ROIs.

Provides some basic functionality that is likely to be shared between all ROIs, and serve as a common type that can be checked for.

Sets up events.changed event, and inits HasTraits.

is_valid()

Determine if the ROI is in a valid state.

This is typically determined by all the coordinates being defined, and that the values makes sense relative to each other.

property ndim
update()

Function responsible for updating anything that depends on the ROI. It should be called by implementors whenever the ROI changes. The base implementation simply triggers the changed event.

class hyperspy.roi.CircleROI(cx, cy, r, r_inner=None)

Bases: hyperspy.roi.BaseInteractiveROI

gui(display=True, toolkit=None, **kwargs)

Display or return interactive GUI element if available.

Parameters

  • display (bool) – If True, display the user interface widgets. If False, return the widgets container in a dictionary, usually for customisation or testing.

  • toolkit (str, iterable of strings or None) – If None (default), all available widgets are displayed or returned. If string, only the widgets of the selected toolkit are displayed if available. If an interable of toolkit strings, the widgets of all listed toolkits are displayed or returned.

is_valid()

Determine if the ROI is in a valid state.

This is typically determined by all the coordinates being defined, and that the values makes sense relative to each other.

class hyperspy.roi.Line2DROI(x1, y1, x2, y2, linewidth=0)

Bases: hyperspy.roi.BaseInteractiveROI

angle(axis='horizontal', units='degrees')

“Angle between ROI line and selected axis

Parameters

  • axis (str, {'horizontal', 'vertical'}, optional) – Select axis against which the angle of the ROI line is measured. ‘x’ is alias to ‘horizontal’ and ‘y’ is ‘vertical’ (Default: ‘horizontal’)

  • units (str, {'degrees', 'radians'}) – The angle units of the output (Default: ‘degrees’)

Returns

angle

Return type

float

Examples

>>> import hyperspy.api as hs
>>> hs.roi.Line2DROI(0., 0., 1., 2., 1)
>>> r.angle()
63.43494882292201
gui(display=True, toolkit=None, **kwargs)

Display or return interactive GUI element if available.

Parameters

  • display (bool) – If True, display the user interface widgets. If False, return the widgets container in a dictionary, usually for customisation or testing.

  • toolkit (str, iterable of strings or None) – If None (default), all available widgets are displayed or returned. If string, only the widgets of the selected toolkit are displayed if available. If an interable of toolkit strings, the widgets of all listed toolkits are displayed or returned.

is_valid()

Determine if the ROI is in a valid state.

This is typically determined by all the coordinates being defined, and that the values makes sense relative to each other.

property length
static profile_line(img, src, dst, axes, linewidth=1, order=1, mode='constant', cval=0.0)

Return the intensity profile of an image measured along a scan line.

Parameters

  • img (numeric array, shape (M, N[, C])) – The image, either grayscale (2D array) or multichannel (3D array, where the final axis contains the channel information).

  • src (2-tuple of numeric scalar (float or int)) – The start point of the scan line.

  • dst (2-tuple of numeric scalar (float or int)) – The end point of the scan line.

  • linewidth (int, optional) – Width of the scan, perpendicular to the line

  • order (int in {0, 1, 2, 3, 4, 5}, optional) – The order of the spline interpolation to compute image values at non-integer coordinates. 0 means nearest-neighbor interpolation.

  • mode (string, one of {'constant', 'nearest', 'reflect', 'wrap'},) – optional How to compute any values falling outside of the image.

  • cval (float, optional) – If mode is ‘constant’, what constant value to use outside the image.

Returns

return_value – The intensity profile along the scan line. The length of the profile is the ceil of the computed length of the scan line.

Return type

array

Examples

>>> x = np.array([[1, 1, 1, 2, 2, 2]])
>>> img = np.vstack([np.zeros_like(x), x, x, x, np.zeros_like(x)])
>>> img
array([[0, 0, 0, 0, 0, 0],
       [1, 1, 1, 2, 2, 2],
       [1, 1, 1, 2, 2, 2],
       [1, 1, 1, 2, 2, 2],
       [0, 0, 0, 0, 0, 0]])
>>> profile_line(img, (2, 1), (2, 4))
array([ 1.,  1.,  2.,  2.])

Notes

The destination point is included in the profile, in contrast to standard numpy indexing.

class hyperspy.roi.Point1DROI(value)

Bases: hyperspy.roi.BasePointROI

Selects a single point in a 1D space. The coordinate of the point in the 1D space is stored in the ‘value’ trait.

gui(display=True, toolkit=None, **kwargs)

Display or return interactive GUI element if available.

Parameters

  • display (bool) – If True, display the user interface widgets. If False, return the widgets container in a dictionary, usually for customisation or testing.

  • toolkit (str, iterable of strings or None) – If None (default), all available widgets are displayed or returned. If string, only the widgets of the selected toolkit are displayed if available. If an interable of toolkit strings, the widgets of all listed toolkits are displayed or returned.

is_valid()

Determine if the ROI is in a valid state.

This is typically determined by all the coordinates being defined, and that the values makes sense relative to each other.

class hyperspy.roi.Point2DROI(x, y)

Bases: hyperspy.roi.BasePointROI

Selects a single point in a 2D space. The coordinates of the point in the 2D space are stored in the traits ‘x’ and ‘y’.

gui(display=True, toolkit=None, **kwargs)

Display or return interactive GUI element if available.

Parameters

  • display (bool) – If True, display the user interface widgets. If False, return the widgets container in a dictionary, usually for customisation or testing.

  • toolkit (str, iterable of strings or None) – If None (default), all available widgets are displayed or returned. If string, only the widgets of the selected toolkit are displayed if available. If an interable of toolkit strings, the widgets of all listed toolkits are displayed or returned.

is_valid()

Determine if the ROI is in a valid state.

This is typically determined by all the coordinates being defined, and that the values makes sense relative to each other.

class hyperspy.roi.RectangularROI(left, top, right, bottom)

Bases: hyperspy.roi.BaseInteractiveROI

Selects a range in a 2D space. The coordinates of the range in the 2D space are stored in the traits ‘left’, ‘right’, ‘top’ and ‘bottom’. Convenience properties ‘x’, ‘y’, ‘width’ and ‘height’ are also available, but cannot be used for initialization.

gui(display=True, toolkit=None, **kwargs)

Display or return interactive GUI element if available.

Parameters

  • display (bool) – If True, display the user interface widgets. If False, return the widgets container in a dictionary, usually for customisation or testing.

  • toolkit (str, iterable of strings or None) – If None (default), all available widgets are displayed or returned. If string, only the widgets of the selected toolkit are displayed if available. If an interable of toolkit strings, the widgets of all listed toolkits are displayed or returned.

property height

Returns / sets the height of the ROI

is_valid()

Determine if the ROI is in a valid state.

This is typically determined by all the coordinates being defined, and that the values makes sense relative to each other.

property width

Returns / sets the width of the ROI

property x

Returns / sets the x coordinate of the ROI without changing its width

property y

Returns / sets the y coordinate of the ROI without changing its height

class hyperspy.roi.SpanROI(left, right)

Bases: hyperspy.roi.BaseInteractiveROI

Selects a range in a 1D space. The coordinates of the range in the 1D space are stored in the traits ‘left’ and ‘right’.

gui(display=True, toolkit=None, **kwargs)

Display or return interactive GUI element if available.

Parameters

  • display (bool) – If True, display the user interface widgets. If False, return the widgets container in a dictionary, usually for customisation or testing.

  • toolkit (str, iterable of strings or None) – If None (default), all available widgets are displayed or returned. If string, only the widgets of the selected toolkit are displayed if available. If an interable of toolkit strings, the widgets of all listed toolkits are displayed or returned.

is_valid()

Determine if the ROI is in a valid state.

This is typically determined by all the coordinates being defined, and that the values makes sense relative to each other.

hyperspy.roi.guess_vertical_or_horizontal(axes, signal)