`hyperspy.api.roi`#

`hyperspy.api.roi.CircleROI`([cx, cy, r, r_inner])	Selects a circular or annular region in a 2D space.
`hyperspy.api.roi.Line2DROI`([x1, y1, x2, y2, ...])	Selects a line of a given width in 2D space.
`hyperspy.api.roi.Point1DROI`([value])	Selects a single point in a 1D space.
`hyperspy.api.roi.Point2DROI`([x, y])	Selects a single point in a 2D space.
`hyperspy.api.roi.RectangularROI`([left, top, ...])	Selects a range in a 2D space.
`hyperspy.api.roi.SpanROI`([left, right])	Selects a range in a 1D space.

Region of interests (ROIs) operate on BaseSignal instances and include widgets for interactive operation.

The following 1D ROIs are available:

1D ROIs#
`Point1DROI`	Single element ROI of a 1D signal
`SpanROI`	Interval ROI of a 1D signal

The following 2D ROIs are available:

2D ROIs#
`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
`PolygonROI`	Polygonal ROI with a customisable shape.

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

Bases: BaseInteractiveROI

Selects a circular or annular region in a 2D space. The coordinates of the center of the circle are stored in the ‘cx’ and ‘cy’ attributes. The radius in the r attribute. If an internal radius is defined using the r_inner attribute, then an annular region is selected instead. CircleROI can be used in place of a tuple containing (cx, cy, r), (cx, cy, r, r_inner) when r_inner is not None.

Sets up events.changed event, and inits HasTraits.

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

Display or return interactive GUI element if available.

Parameters:

displaybool: If True, display the user interface widgets. If False, return the widgets container in a dictionary, usually for customisation or testing.
toolkitstr, iterable of str 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.api.roi.Line2DROI(x1=None, y1=None, x2=None, y2=None, linewidth=0)#

Bases: BaseInteractiveROI

Selects a line of a given width in 2D space. The coordinates of the end points of the line are stored in the x1, y1, x2, y2 parameters. The length is available in the length parameter and the method angle computes the angle of the line with the axes.

Line2DROI can be used in place of a tuple containing the coordinates of the two end-points of the line and the linewdith (x1, y1, x2, y2, linewidth).

Sets up events.changed event, and inits HasTraits.

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

“Angle between ROI line and selected axis

Parameters:

axisstr, {‘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’)
unitsstr, {‘degrees’, ‘radians’}: The angle units of the output (Default: ‘degrees’)

Returns:

anglefloat

Examples

>>> r = hs.roi.Line2DROI(0., 0., 1., 2.)
>>> print(r.angle())
63.43494882292201

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

Display or return interactive GUI element if available.

Parameters:

displaybool: If True, display the user interface widgets. If False, return the widgets container in a dictionary, usually for customisation or testing.
toolkitstr, iterable of str 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.

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:

imgnumpy.ndarray: The image, either grayscale (2D array) or multichannel (3D array, where the final axis contains the channel information).
srctuple of float, tuple of int: The start point of the scan line. Length of tuple is 2.
dsttuple of float, tuple of int: The end point of the scan line. Length of tuple is 2.
linewidthint, optional: Width of the scan, perpendicular to the line
order{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{‘constant’, ‘nearest’, ‘reflect’, ‘wrap’}, optional: How to compute any values falling outside of the image.
cvalfloat, optional: If mode='constant', what constant value to use outside the image.

Returns:

numpy.ndarray: The intensity profile along the scan line. The length of the profile is the ceil of the computed length of the scan line.

Notes

The destination point is included in the profile, in contrast to standard numpy indexing. Requires uniform navigation axes.

class hyperspy.api.roi.Point1DROI(value=None)#

Bases: BasePointROI

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

Point1DROI can be used in place of a tuple containing the value of value.

Examples

>>> roi = hs.roi.Point1DROI(0.5)
>>> value, = roi
>>> print(value)
0.5

Sets up events.changed event, and inits HasTraits.

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

Display or return interactive GUI element if available.

Parameters:

displaybool: If True, display the user interface widgets. If False, return the widgets container in a dictionary, usually for customisation or testing.
toolkitstr, iterable of str 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.

class hyperspy.api.roi.Point2DROI(x=None, y=None)#

Bases: 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'.

Point2DROI can be used in place of a tuple containing the coordinates of the point (x, y).

Examples

>>> roi = hs.roi.Point2DROI(3, 5)
>>> x, y = roi
>>> print(x, y)
3.0 5.0

Sets up events.changed event, and inits HasTraits.

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

Display or return interactive GUI element if available.

Parameters:

displaybool: If True, display the user interface widgets. If False, return the widgets container in a dictionary, usually for customisation or testing.
toolkitstr, iterable of str 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.

class hyperspy.api.roi.PolygonROI(vertices=None)#

Bases: BaseInteractiveROI

Selects a polygonal region in a 2D space. The coordinates of the polygon vertices are given in the vertices attribute, which is a list where each entry is a tuple (x, y) of a vertex’s coordinates. An edge runs from the final to the first point in the list. If a polygon self overlaps, the overlapping areas may be considered outside of the polygon and masked away.

Parameters:

verticeslist of tuple: List containing (x, y) values of the vertices of a polygon.

is_valid()#: The polygon is defined as valid if either zero or more than two vertices are fully defined.

property vertices#: Returns a list where each entry contains a (x, y) tuple of the vertices of the polygon. The polygon is not closed. Returns an empty list if no polygon is set.

class hyperspy.api.roi.RectangularROI(left=None, top=None, right=None, bottom=None)#

Bases: 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.

RectangularROI can be used in place of a tuple containing (left, right, top, bottom).

Examples

>>> roi = hs.roi.RectangularROI(left=0, right=10, top=20, bottom=20.5)
>>> left, right, top, bottom = roi
>>> print(left, right, top, bottom)
0.0 10.0 20.0 20.5

Sets up events.changed event, and inits HasTraits.

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

Display or return interactive GUI element if available.

Parameters:

displaybool: If True, display the user interface widgets. If False, return the widgets container in a dictionary, usually for customisation or testing.
toolkitstr, iterable of str 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.api.roi.SpanROI(left=None, right=None)#

Bases: 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'.

SpanROI can be used in place of a tuple containing the left and right values.

Examples

>>> roi = hs.roi.SpanROI(-3, 5)
>>> left, right = roi
>>> print(left, right)
-3.0 5.0

Sets up events.changed event, and inits HasTraits.

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

Display or return interactive GUI element if available.

Parameters:

displaybool: If True, display the user interface widgets. If False, return the widgets container in a dictionary, usually for customisation or testing.
toolkitstr, iterable of str 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.api.roi.combine_rois(signal, rois, inverted=False, out=None, axes=None)#

Slice the signal according by combining a list of ROIs, by default returning a sliced copy. Currently only implemented for a list of PolygonROI.

Parameters:

signalBaseSignal: The signal to slice with the ROI.
roislist of PolygonROI: List containing the ROIs to be sliced, making it possible to combine several ROI shapes.
invertedbool, default = False: If True, everything outside of the ROIs supplied will be retained, with the insides of the ROIs becoming numpy.nan.
outBaseSignal, default = None: If the out argument is supplied, the sliced output will be put into this instead of returning a BaseSignal.
axeslist, optional: List of the axes in the signal that the ROIs are applied to.

hyperspy.api.roi.mask_from_rois(rois, axes_manager=None, axes=None, xy_max=None, xy_min=None, x_scale=None, y_scale=None)#

Function to rasterize a list of ROIs into a boolean numpy array. The interior of the ROIs are by default True. Currently only implemented for a list of PolygonROI.

Parameters:

roislist of PolygonROI: List containing the ROIs to be added to the mask, making it possible to combine several ROI shapes.
axes_managerAxesManager, optional: If supplied, the rasterization parameters not explicitly given will be extracted from this. The axes can be given with the axes attribute.
axeslist, optional: List of the axes in axes_manager that are to be used as a basis for the rasterization if other parameters aren’t supplied.
xy_maxtuple, optional: The maximum x and y values that the rasterized mask covers, given in the same coordinate space as the polygon vertices. The defaults are the max values in the vertices of the supplied ROIs.
xy_mintuple, optional: The minimum x and y values that the mask covers, given in the same coordinate space as the polygon vertices. The default is from (0, 0).
x_scalefloat, optional: This gives the scale of the second axis of the signal. In other words, how many units in coordinate space that corresponds to one step between columns. Default is 1.
y_scalefloat, optional: This gives the scale of the second axis of the signal. In other words, how many units in coordinate space that corresponds to one step between rows. Default is 1.

Returns:

return_valuenumpy.ndarray: boolean numpy array of the rasterized ROIs. Depending on the limits set for the rasterization, parts of the ROIs may be outside of this.

hyperspy.api.roi#

`hyperspy.api.roi`#