hyperspy.drawing.widget module

class hyperspy.drawing.widget.DraggableWidgetBase(axes_manager, **kwargs)

Bases: hyperspy.drawing.widget.WidgetBase

Adds the position and indices properties, and adds a framework for letting the user drag the patch around. Also adds the moved event.

The default behavior is that position snaps to the values corresponding to the values of the axes grid (i.e. no subpixel values). This behavior can be controlled by the property snap_position.

Any inheritors must override these methods:

_onmousemove(self, event) _update_patch_position(self) _set_patch(self)

_do_snap_position(value=None)

Snaps position to axes grid. Returns snapped value. If value is passed as an argument, the internal state is left untouched, if not the position attribute is updated to the snapped value.

_get_indices()

Returns a tuple with the position (indices).

_get_position()

Provides the position of the widget (by values) in a tuple.

_on_navigate(axes_manager)

Callback for axes_manager’s change notification.

_onmousemove(event)

Callback for mouse movement. For dragging, the implementor would normally check that the widget is picked, and that the event.inaxes Axes equals self.ax.

_pos_changed()

Call when the position of the widget has changed. It triggers the relevant events, and updates the patch position.

_set_indices(value)

Sets the position of the widget (by indices). The dimensions should correspond to that of the ‘axes’ attribute. Calls _pos_changed if the value has changed, which is then responsible for triggering any relevant events.

_set_position(position)

Sets the position of the widget (by values). The dimensions should correspond to that of the ‘axes’ attribute. Calls _pos_changed if the value has changed, which is then responsible for triggering any relevant events.

_update_patch_geometry()

Updates all geometrical properties of the patch on the plot.

_update_patch_position()

Updates the position of the patch on the plot.

_validate_pos(pos)

Validates the passed position. Depending on the position and the implementation, this can either fire a ValueError, or return a modified position that has valid values. Or simply return the unmodified position if everything is ok.

This default implementation bounds the position within the axes limits.

button_release(event)

whenever a mouse button is released.

connect(ax)

Connect to the matplotlib Axes’ events.

class hyperspy.drawing.widget.ResizableDraggableWidgetBase(axes_manager, **kwargs)

Bases: hyperspy.drawing.widget.DraggableWidgetBase

Adds the size property and get_size_in_axes method, and adds a framework for letting the user resize the patch, including resizing by key strokes (‘+’, ‘-‘). Also adds the ‘resized’ event.

Utility functions for resizing are implemented by increase_size and decrease_size, which will in-/decrement the size by 1. Other utility functions include get_centre and get_centre_indices which returns the center position, and the internal _apply_changes which helps make sure that only one ‘changed’ event is fired for a combined move and resize.

Any inheritors must override these methods:

_update_patch_position(self) _update_patch_size(self) _update_patch_geometry(self) _set_patch(self)

_apply_changes(old_size, old_position)

Evaluates whether the widget has been moved/resized, and triggers the correct events and updates the patch geometry. This function has the advantage that the geometry is updated only once, preventing flickering, and the ‘changed’ event only fires once.

_get_size()

Getter for ‘size’ property. Returns the size as a tuple (to prevent unintended in-place changes).

_set_size(value)

Setter for the ‘size’ property.

Calls _size_changed to handle size change, if the value has changed.

_size_changed()

Triggers resize and changed events, and updates the patch.

_update_patch_geometry()

Updates all geometry of the patch on the plot.

_update_patch_size()

Updates the size of the patch on the plot.

button_release(event)

whenever a mouse button is released.

connect(ax)

Connect to the matplotlib Axes’ events.

decrease_size()

Decrement all sizes by 1. Applied via ‘size’ property.

get_centre()

Gets the center indices. The default implementation is simply the position + half the size in axes space, which should work for any symmetric widget, but more advanced widgets will need to decide whether to return the center of gravity or the geometrical center of the bounds.

get_centre_index()

Gets the center position (in index space). The default implementation is simply the indices + half the size, which should work for any symmetric widget, but more advanced widgets will need to decide whether to return the center of gravity or the geometrical center of the bounds.

get_size_in_indices()

Gets the size property converted to the index space (via ‘axes’ attribute).

increase_size()

Increment all sizes by 1. Applied via ‘size’ property.

set_size_in_indices(value)

Sets the size property converted to the index space (via ‘axes’ attribute).

class hyperspy.drawing.widget.ResizersMixin(resizers=True, **kwargs)

Bases: object

Widget mix-in for adding resizing manipulation handles.

The default handles are green boxes displayed on the outside corners of the boundaries. By default, the handles are only displayed when the widget is selected (picked in matplotlib terminology).

resizers

Property that determines whether the resizer handles should be used

Type

bool

resize_color

The color of the resize handles.

Type

matplotlib color

resize_pixel_size

Size of the resize handles in screen pixels. If None, it is set equal to the size of one ‘data-pixel’ (image pixel size).

Type

tuple or None

resizer_picked

Inidcates which, if any, resizer was selected the last time the widget was picked. False if another patch was picked, or the index of the resizer handle that was picked.

Type

False or int

_add_patch_to(ax)

Same as widget base, but also adds resizers if ‘resizers’ property is True.

_get_resizer_offset()

Utility for getting the distance from the boundary box to the center of the resize handles.

_get_resizer_pos()

Get the positions of the resizer handles.

_get_resizer_size()

Gets the size of the resizer handles in axes coordinates. If ‘resize_pixel_size’ is None, a size of one pixel will be used.

_set_patch()

Creates the resizer handles, regardless of whether they will be used or not.

_set_resizers(value, ax)

Turns the resizers on/off, in much the same way that _set_patch works.

_update_resizers()

Update resizer handles’ patch geometry.

onpick(event)

Picking of main patch is same as for widget base, but this also handles picking of the resize handles. If a resize handle is picked, picked is set to True, and resizer_picked is set to an integer indicating which handle was picked (0-3 for top left, top right, bottom left, bottom right). It is set to False if another widget was picked.

If the main patch is picked, the offset from the picked pixel to the position is stored in pick_offset. This can be used in e.g. _onmousemove to ease dragging code (prevent widget center/corner snapping to mouse).

set_on(value)

Turns on/off resizers whet widget is turned on/off.

class hyperspy.drawing.widget.Widget1DBase(axes_manager, **kwargs)

Bases: hyperspy.drawing.widget.DraggableWidgetBase

A base class for 1D widgets.

It sets the right dimensions for size and position, adds the ‘border_thickness’ attribute and initalizes the ‘axes’ attribute to the first two navigation axes if possible, if not, the two first signal_axes are used. Other than that, it mainly supplies common utility functions for inheritors, and implements required functions for ResizableDraggableWidgetBase.

The implementation for ResizableDraggableWidgetBase methods all assume that a Rectangle patch will be used, centered on position. If not, the inheriting class will have to override those as applicable.

_set_position(position)

Sets the position of the widget (by values). The dimensions should correspond to that of the ‘axes’ attribute. Calls _pos_changed if the value has changed, which is then responsible for triggering any relevant events.

_validate_pos(pos)

Validates the passed position. Depending on the position and the implementation, this can either fire a ValueError, or return a modified position that has valid values. Or simply return the unmodified position if everything is ok.

This default implementation bounds the position within the axes limits.

class hyperspy.drawing.widget.Widget2DBase(axes_manager, **kwargs)

Bases: hyperspy.drawing.widget.ResizableDraggableWidgetBase

A base class for 2D widgets. It sets the right dimensions for size and position, adds the ‘border_thickness’ attribute and initalizes the ‘axes’ attribute to the first two navigation axes if possible, if not, the two first signal_axes are used. Other than that it mainly supplies common utility functions for inheritors, and implements required functions for ResizableDraggableWidgetBase.

The implementation for ResizableDraggableWidgetBase methods all assume that a Rectangle patch will be used, centered on position. If not, the inheriting class will have to override those as applicable.

_get_patch_bounds()

Returns the bounds of the patch in the form of a tuple in the order left, top, width, height. In matplotlib, ‘bottom’ is used instead of ‘top’ as the naming assumes an upwards pointing y-axis, meaning the lowest value corresponds to bottom. However, our widgets will normally only go on images (which has an inverted y-axis in MPL by default), so we define the lowest value to be termed ‘top’.

_get_patch_xy()

Returns the xy position of the widget. In this default implementation, the widget is centered on the position.

_update_patch_geometry()

Updates all geometry of the patch on the plot.

_update_patch_position()

Updates the position of the patch on the plot.

_update_patch_size()

Updates the size of the patch on the plot.

class hyperspy.drawing.widget.WidgetBase(axes_manager=None, color='red', alpha=1.0, **kwargs)

Bases: object

Base class for interactive widgets/patches. A widget creates and maintains one or more matplotlib patches, and manages the interaction code so that the user can maniuplate it on the fly.

This base class implements functionality which is common to all such widgets, mainly the code that manages the patch, axes management, and sets up common events (‘changed’ and ‘closed’).

Any inherting subclasses must implement the following methods:

_set_patch(self) _on_navigate(obj, name, old, new) # Only for widgets that can navigate

It should also make sure to fill the ‘axes’ attribute as early as possible (but after the base class init), so that it is available when needed.

_add_patch_to(ax)

Create and add the matplotlib patches to ‘ax’

_i2v(axis, i)

Wrapped version of DataAxis.index2value, which bounds the value between axis.low_value and axis.high_value+axis.scale, and does not raise a ValueError.

_on_navigate(axes_manager)

Callback for axes_manager’s change notification.

_set_patch()

Create the matplotlib patch(es), and store it in self.patch

_v2i(axis, v)

Wrapped version of DataAxis.value2index, which bounds the index between axis.low_index and axis.high_index+1, and does not raise a ValueError.

close(window=None, render_figure=False)

Set the on state to off (removes patch and disconnects), and trigger events.closed.

connect(ax)

Connect to the matplotlib Axes’ events.

connect_navigate()

Connect to the axes_manager such that changes in the widget or in the axes_manager are reflected in the other.

disconnect()

Disconnect from all events (both matplotlib and navigation).

disconnect_navigate()

Disconnect a previous naivgation connection.

draw_patch(*args)

Update the patch drawing.

property is_on

Determines if the widget is set to draw if valid (turned on).

select()

Cause this widget to be the selected widget in its MPL axes. This assumes that the widget has its patch added to the MPL axes.

set_mpl_ax(ax)

Set the matplotlib Axes that the widget will draw to. If the widget on state is True, it will also add the patch to the Axes, and connect to its default events.

set_on(value, render_figure=True)

Change the on state of the widget. If turning off, all patches will be removed from the matplotlib axes and the widget will disconnect from all events. If turning on, the patch(es) will be added to the matplotlib axes, and the widget will connect to its default events.