erlab.interactive.imagetool.core

Provides core functionality of ImageTool.

This module contains ImageSlicerArea which handles the core functionality of ImageTool, including the slicing and plotting of data.

Functions

link_slicer([func, indices, steps, color])	Sync decorated methods across multiple ImageSlicerArea instances.
record_history([method])	Log history before calling the decorated method.
suppress_history([method])	Ignore history changes made within the decorated method.

Classes

ColorMapState	A dictionary containing the colormap state of an ImageSlicerArea instance.
ImageSlicerArea(parent, data[, cmap, gamma, ...])	A interactive tool based on pyqtgraph for exploring 3D data.
ImageSlicerState	A dictionary containing the state of an ImageSlicerArea instance.
ItoolColorBar(slicer_area, **cbar_kw)
ItoolColorBarItem(slicer_area, **kwargs)
ItoolCursorLine(*args, **kargs)	A subclass of pyqtgraph.InfiniteLine used in ImageTool.
ItoolCursorSpan(*args, **kargs)
ItoolDisplayObject(axes[, cursor])	Parent class for sliced data.
ItoolGraphicsLayoutWidget(slicer_area, ...)
ItoolImageItem(axes[, cursor])	Display a 2D slice of data as an image.
ItoolPlotDataItem(axes[, cursor, is_vertical])	Display a 1D slice of data in a plot.
ItoolPlotItem(slicer_area, display_axis, ...)	A subclass of pyqtgraph.PlotItem used in ImageTool.
PlotItemState	A dictionary containing the state of a PlotItem instance.
SlicerLinkProxy(*slicers[, link_colors])	Internal class for handling linked ImageSlicerArea s.

class erlab.interactive.imagetool.core.ColorMapState

Bases: TypedDict

A dictionary containing the colormap state of an ImageSlicerArea instance.

cmap: str | ColorMap

gamma: float

reverse: bool

high_contrast: bool

zero_centered: bool

levels_locked: bool

levels: NotRequired[tuple[float, float]]

class erlab.interactive.imagetool.core.PlotItemState

Bases: TypedDict

A dictionary containing the state of a PlotItem instance.

vb_aspect_locked: bool | float

vb_x_inverted: bool

vb_y_inverted: bool

class erlab.interactive.imagetool.core.ImageSlicerState

Bases: TypedDict

A dictionary containing the state of an ImageSlicerArea instance.

color: ColorMapState

slice: ArraySlicerState

current_cursor: int

manual_limits: dict[str, list[float]]

cursor_colors: list[str]

file_path: typing.NotRequired[str | None]

splitter_sizes: typing.NotRequired[list[list[int]]]

plotitem_states: typing.NotRequired[list[PlotItemState]]

class erlab.interactive.imagetool.core.ItoolGraphicsLayoutWidget(slicer_area, display_axis, axis_enabled, image=False, **item_kw)

Bases: PlotWidget

getPlotItem()

erlab.interactive.imagetool.core.suppress_history(method=None)

Ignore history changes made within the decorated method.

erlab.interactive.imagetool.core.record_history(method=None)

Log history before calling the decorated method.

erlab.interactive.imagetool.core.link_slicer(func=None, *, indices=False, steps=False, color=False)

Sync decorated methods across multiple ImageSlicerArea instances.

Parameters:

• func (Callable | None, default: None) – The method to sync across multiple instances of ImageSlicerArea.

• indices (bool, default: False) – If True, the input argument named value given to func are interpreted as indices, and will be converted to appropriate values for other instances of ImageSlicerArea. The behavior of this conversion is determined by steps. If True, An input argument named axis of type integer must be present in the decorated method to determine the axis along which the index is to be changed.

• steps (bool, default: False) – If False, considers value as an absolute index. If True, considers value as a relative value such as the number of steps or bins. See the implementation of SlicerLinkProxy for more information.

• color (bool, default: False) – Boolean whether the decorated method is related to visualization, such as colormap control.

class erlab.interactive.imagetool.core.SlicerLinkProxy(*slicers, link_colors=True)

Bases: object

Internal class for handling linked ImageSlicerArea s.

Parameters:

• *slicers (ImageSlicerArea) – The slicers to link.

• link_colors (bool, default: True) – Whether to sync color related changes, by default True.

property children: WeakSet

property num_children: int

unlink_all()

add(slicer_area)

remove(slicer_area)

sync(source, funcname, arguments, indices, steps, color)

Propagate changes across multiple ImageSlicerAreas.

This method is invoked every time a method decorated with link_slicer() in a linked ImageSlicerArea is called.

Parameters:

• source (ImageSlicerArea) – Instance of ImageSlicerArea corresponding to the called method.

• funcname (str) – Name of the called method.

• arguments (dict[str, Any]) – Arguments included in the function call.

• indices (bool) – Arguments given to the decorator. See link_slicer()

• steps (bool) – Arguments given to the decorator. See link_slicer()

• color (bool) – Arguments given to the decorator. See link_slicer()

convert_args(source, target, args, indices, steps)

static convert_index(source, target, axis, index, steps)

class erlab.interactive.imagetool.core.ImageSlicerArea(parent, data, cmap=None, gamma=None, high_contrast=False, zero_centered=False, vmin=None, vmax=None, rad2deg=False, *, transpose=False, bench=False, state=None, file_path=None, image_cls=None, plotdata_cls=None, _in_manager=False, _disable_reload=False)

Bases: QWidget

A interactive tool based on pyqtgraph for exploring 3D data.

Parameters:

• parent (QWidget) – Parent widget.

• data (DataArray or array-like) – Data to display. The data must have 2 to 4 dimensions.

• cmap (str | ColorMap | None, default: None) – Default colormap of the data.

• gamma (float, optional) – Default power law normalization of the colormap.

• high_contrast (bool, default: False) – If True, the colormap is displayed in high contrast mode. This changes the behavior of the exponent scaling of the colormap. See erlab.plotting.colors for a detailed explanation of the difference.

• zero_centered (bool, default: False) – If True, the normalization is applied symmetrically from the midpoint of the colormap.

• vmin (float | None, default: None) – Minimum value of the colormap.

• vmax (float | None, default: None) – Maximum value of the colormap.

• rad2deg (bool | Iterable[str], default: False) – If True and data is not None, converts some known angle coordinates to degrees. If an iterable of strings is given, only the coordinates that correspond to the given strings are converted.

• transpose (bool, default: False) – If True, the main image is transposed before being displayed.

• bench (bool, default: False) – Prints the fps on Ctrl + drag for debugging purposes.

• state (ImageSlicerState | None, default: None) – Initial state containing the settings and cursor position.

• file_path (str | PathLike | None, default: None) – If the data has been loaded from a file, the path to the file. This is used to set the window title.

Signals:

• sigDataChanged()

• sigCurrentCursorChanged(index)

• sigViewOptionChanged()

• sigHistoryChanged()

• sigWriteHistory()

• sigCursorColorsChanged()

• sigDataEdited() – Signal to track when the data has been modified by user actions.

• sigCursorCountChanged(n_cursors) – Inherited from erlab.interactive.slicer.ArraySlicer.

• sigIndexChanged(cursor, axes) – Inherited from erlab.interactive.slicer.ArraySlicer.

• sigBinChanged(cursor, axes) – Inherited from erlab.interactive.slicer.ArraySlicer.

• sigShapeChanged() – Inherited from erlab.interactive.slicer.ArraySlicer.

• sigTwinChanged() – Inherited from erlab.interactive.slicer.ArraySlicer.

property COLORS: tuple[QColor, ...]

PySide6.QtGui.QColors for multiple cursors.

TWIN_COLORS: tuple[QColor, ...] = (<PyQt6.QtGui.QColor object>, <PyQt6.QtGui.QColor object>, <PyQt6.QtGui.QColor object>, <PyQt6.QtGui.QColor object>, <PyQt6.QtGui.QColor object>)

PySide6.QtGui.QColors for twin plots.

HORIZ_PAD: int = 45

Reserved space for the x axes in each plot.

VERT_PAD: int = 30

Reserved space for the y axes in each plot.

TICK_FONT_SIZE: float = 11.0

Font size of axis ticks in points.

property parent_title: str

property display_name: str

Generate a display name for the slicer.

Depending on the source of the data and the ‘name’ attribute of the underlying DataArray, the display name is generated differently.

If nothing can be inferred, an empty string is returned.

property colormap_properties: ColorMapState

property state: ImageSlicerState

property splitter_sizes: list[list[int]]

property is_linked: bool

property linked_slicers: WeakSet

property colormap: str | ColorMap

property levels_locked: bool

property levels: tuple[float, float]

property slices: tuple[ItoolPlotItem, ...]

property profiles: tuple[ItoolPlotItem, ...]

property main_image: ItoolPlotItem

Return the main PlotItem.

property images: tuple[ItoolPlotItem, ...]

property axes: tuple[ItoolPlotItem, ...]

Currently valid subset of self._plots.

property array_slicer: ArraySlicer

property n_cursors: int

property current_indices: list[int]

property current_values: list[float]

property current_values_uniform: list[float]

property data: DataArray

property undoable: bool

property redoable: bool

history_suppressed()

write_state()

flush_history()

Clear the undo and redo history.

undo()

Undo the most recent action.

redo()

Redo the most recently undone action.

initialize_actions()

Initialize QtWidgets.QAction instances.

edit_cursor_colors()

Open a dialog to edit cursor colors.

refresh_actions_enabled()

Refresh the enabled state of miscellaneous actions.

This slot is triggered from the parent widget when the menubar containing the actions is about to be shown.

connect_axes_signals()

disconnect_axes_signals()

connect_signals()

link(proxy)

unlink()

get_current_index(axis)

get_current_value(axis, uniform=False)

get_axes_widget(index)

get_axes(index)

close_associated_windows()

refresh_all(axes=None, only_plots=False)

refresh_current(axes=None)

refresh(cursor, axes=None)

view_all()

center_all_cursors()

center_cursor()

set_current_cursor(cursor, update=True)

set_data(data, rad2deg=False, file_path=None, auto_compute=True)

Set the data to be displayed.

Parameters:

• data (DataArray | ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]) – The data to be displayed. If a xarray.DataArray is given, the dimensions and coordinates are used to determine the axes of the plots. If a xarray.Dataset is given, the first data variable is used. If a numpy.ndarray is given, it is converted to a xarray.DataArray with default dimensions.

• rad2deg (bool | Iterable[str], default: False) – If True, converts coords along dimensions that have angle-like names to degrees. If an iterable of strings is given, coordinates for dimensions that correspond to the given strings are converted.

• file_path (str | PathLike | None, default: None) – Path to the file from which the data was loaded. If given, the file path is used to set the window title.

• auto_compute (bool, default: True) – If True and the data is dask-backed, automatically compute the data if its size is below the threshold defined in options.

property reloadable: bool

Check if the data can be reloaded from the file.

The data can be reloaded if the data was loaded from a file that still exists and the data loader name is stored in the data attributes.

Returns:

bool – True if the data can be reloaded, False otherwise.

reload()

Reload the data from the file it was loaded from, using the same loader.

Silently fails if the data cannot be reloaded. If an error occurs while reloading the data, a message is shown to the user.

See also

reloadable

update_values(values, update=True)

Update only the values of the data.

The coords and shape of the data array are not changed.

Parameters:

• values (ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]] | DataArray) – The new values to be set. If a xarray.DataArray is given, the dimensions must match the current data array. If a numpy.ndarray is given, the shape must match the current data array. Note that if the user has transposed the current data array, passing a numpy.ndarray with the original shape will fail.

• update (bool, default: True) – If True, the plots are updated after setting the new values.

Note

This method only checks for matching dimension name and shape, and does not check for equal coordinate values.

apply_func(func, update=True)

Apply a function to the data.

The function must accept the data as the first argument and return a new DataArray. The returned DataArray must have the same dimensions and coordinates as the original data.

This action is not recorded in the history, and the data is not affected. Only one function can be applied at a time.

Parameters:

• func (Callable[[DataArray], DataArray] | None) – The function to apply to the data. if None, the data is restored.

• update (bool, default: True) – If True, the plots are updated after setting the new values.

set_manual_limits(manual_limits)

Set manual limits for the axes.

Replaces the current manual limits with the given limits dictionary and updates all child axes accordingly.

propagate_limit_change(axes)

Propagate manual limits changes to all linked slicers.

Called when the limits of a child axes are changed by the user.

This method first propagates the limits to all linked slicers (if any), and then triggers the update of the manual limits for all other axes. This ensures that all plots share the same limits for a given dimension.

property watched_data_name: str | None

Get the name of the watched data variable.

Only applicable if in an ImageTool Manager and the data is linked to a watched variable in a notebook. Returns None if otherwise.

property data_chunked: bool

Check if the data is chunked (backed by dask).

Returns:

bool – True if the data is chunked, False otherwise.

swap_axes(ax1, ax2)

transpose_main_image()

set_index(axis, value, update=True, cursor=None)

step_index(axis, value, update=True, cursor=None)

step_index_all(axis, value, update=True)

set_value(axis, value, update=True, uniform=False, cursor=None)

set_bin(axis, value, update=True, cursor=None)

set_bin_all(axis, value, update=True)

make_cursors(colors)

Create cursors with the specified colors.

Used when restoring the state of the slicer. All existing cursors are removed.

add_cursor(color=None)

remove_cursor(index)

remove_current_cursor()

toggle_cursor_visibility()

Toggle the visibility of the cursor lines.

color_for_cursor(index)

Pick a cursor color based on the index.

set_cursor_colors(colors)

Set the colors of the cursors.

Parameters:

colors (Iterable[QColor]) – An iterable of colors to set for the cursors.

set_colormap(cmap=None, gamma=None, reverse=None, high_contrast=None, zero_centered=None, levels_locked=None, levels=None, update=True)

refresh_colormap()

lock_levels(lock)

add_tool_window(widget, update_title=True, transfer_to_manager=True)

Save a reference to an additional window widget.

This is mainly used for handling tool windows such as goldtool and dtool.

The tool window is cleared from memory immediately when it is closed. Closing the main window will close all associated tool windows.

Only pass widgets that are not associated with a parent widget.

If the parent ImageTool is in the manager, the widget is transferred to the manager instead

Parameters:

• widget (QWidget) – The widget to add.

• update_title (bool, default: True) – If True, the window title is updated to include the parent title. If False, the window title is not changed.

• transfer_to_manager (bool, default: True) – If True, the ownership of the widget is transferred to the manager if the parent ImageTool is in the manager. Use False for dialog windows that should not be managed by the manager.

open_in_ktool()

Open the interactive momentum conversion tool.

adjust_layout(r=(1.2, 1.5, 3.0, 1.0))

Determine the padding and aspect ratios.

Parameters:

• horiz_pad – Reserved space for the x and y axes.

• vert_pad – Reserved space for the x and y axes.

• font_size – Font size of axis ticks in points.

• r (tuple[float, float, float, float], default: (1.2, 1.5, 3.0, 1.0)) – 4 numbers that determine the aspect ratio of the layout. See notes.

Notes

Axes indices and layout parameters.

     ┌───────────┬───────────┐
r[0] │     1     │     6     │
     │           ├───────────┤
     ├───────────┤     3     │
r[1] │     4     ├───────────┤
     │           │     7     │
     │───────────┼───────┬───┤
     │           │       │   │
r[2] │     0     │   5   │ 2 │
     │           │       │   │
     └───────────┴───────┴───┘
      r[3] * r[2]

toggle_snap(value=None)

changeEvent(evt)

class erlab.interactive.imagetool.core.ItoolCursorLine(*args, **kargs)

Bases: InfiniteLine

A subclass of pyqtgraph.InfiniteLine used in ImageTool.

property plotItem: ItoolPlotItem

setBounds(bounds, value=None)

value()

mouseDragEvent(ev)

mouseClickEvent(ev)

hoverEvent(ev)

class erlab.interactive.imagetool.core.ItoolCursorSpan(*args, **kargs)

Bases: LinearRegionItem

setRegion(rgn)

class erlab.interactive.imagetool.core.ItoolDisplayObject(axes, cursor=None)

Bases: object

Parent class for sliced data.

Stores the axes and cursor index for the object, and retrieves the sliced data from erlab.interactive.imagetool.slicer.ArraySlicer when needed.

property display_axis

property slicer_area: ImageSlicerArea

property array_slicer: ArraySlicer

property cursor_index

property sliced_data: DataArray

refresh_data()

class erlab.interactive.imagetool.core.ItoolPlotDataItem(axes, cursor=None, is_vertical=False, **kargs)

Bases: ItoolDisplayObject, PlotDataItem

Display a 1D slice of data in a plot.

refresh_data()

class erlab.interactive.imagetool.core.ItoolImageItem(axes, cursor=None, **kargs)

Bases: ItoolDisplayObject, BetterImageItem

Display a 2D slice of data as an image.

updateImage(*args, **kargs)

refresh_data()

mouseDragEvent(ev)

mouseClickEvent(ev)

class erlab.interactive.imagetool.core.ItoolPlotItem(slicer_area, display_axis, axis_enabled, image=False, image_cls=None, plotdata_cls=None, **item_kw)

Bases: PlotItem

A subclass of pyqtgraph.PlotItem used in ImageTool.

This class tracks axes and cursors for the data displayed in the plot, and provides context menu actions for interacting with the data.

setup_actions()

connect_signals()

disconnect_signals()

setup_twin()

Initialize twin axis for plotting associated coordinates.

property twin_axes_location: Literal['top', 'bottom', 'left', 'right']

property twin_visible: bool

enableAutoRange(axis=None, enable=True, x=None, y=None)

update_twin_range(autorange=True)

update_twin_plots()

property axis_dims: tuple[str | None, str | None]

Get the names of the data dimensions plotted on each axis.

Removes ‘_idx’ suffix for non-uniform axes.

property axis_dims_uniform: tuple[str | None, str | None]

Get the names of the data dimensions plotted on each axis.

Retains ‘_idx’ suffix for non-uniform axes.

property is_independent: bool

property is_view_cropped: bool

Whether the current view limits are smaller than the full data range.

property current_data: DataArray

Data in the current plot item, optionally cropped to view limits.

If accessed while the Alt (Option) key is pressed, the data is cropped to the current axes view limits.

property selection_code: str

Get the selection code for the data.

Returns a string that looks like .sel(...) or .qsel(...) that selects the current slice of data based on the current cursor location and bin size.

get_selection_code(placeholder='data')

Get selection code for the current cursor and display axis.

Adds a placeholder data name as a prefix to the selection code returned by selection_code. If the data is linked to a watched variable in a notebook through the ImageTool manager, the variable name in the notebook is used instead.

Parameters:

placeholder (str, optional) – Name to fall back to if the data is not linked to a watched variable in a notebook. By default, uses “data”.

property is_guidelines_visible: bool

set_normalize(normalize)

Toggle normalization for 1D plots.

open_in_new_window()

Open the current data in a new window. Only available for 2D data.

open_in_goldtool()

open_in_restool()

open_in_dtool()

normalize_to_current_view()

Adjust color limits to the currently visible area.

Only available for image plots.

Sets the color limits of the slicer area to the min and max of the currently visible area of this image (similar to AdjustCT in ImageTool).

range_changed_manually()

Propagate manual range changes to other plots.

This slot propagates the limit change to related other plots in the same slicer area, and to other linked slicer areas.

refresh_manual_range()

Store manual limit changes in the parent slicer area.

This slot ensures that the manual limits stored in the parent slicer area are always up to date with the current view range.

When a user manually changes the view range, this slot is called before range_changed_manually is called.

update_manual_range()

Update view range from values stored in the parent slicer area.

set_range_from(limits, **kwargs)

toggle_aspect_equal()

getMenu()

getViewBox()

mouseDragEvent(ev)

process_drag(sig)

set_cursor_colors(colors)

Set the colors of the cursors and spans.

add_cursor(update=True)

set_cursor_visible(visible)

Set visibility of all cursors.

index_of_line(line)

line_click(line)

line_drag(line, value, axis)

remove_cursor(index)

refresh_cursor(cursor)

set_guidelines(n)

Show rotating crosshairs for alignment.

remove_guidelines()

Hide rotating crosshairs.

refresh_items_data(cursor, axes=None)

refresh_labels()

set_active_cursor(index)

save_current_data()

copy_selection_code()

property display_axis: tuple[int, ...]

property slicer_area: ImageSlicerArea

property array_slicer: ArraySlicer

changeEvent(evt)

class erlab.interactive.imagetool.core.ItoolColorBarItem(slicer_area, **kwargs)

Bases: BetterColorBarItem

property slicer_area: ImageSlicerArea

property images

property primary_image

setImageItem(*args, **kwargs)

class erlab.interactive.imagetool.core.ItoolColorBar(slicer_area, **cbar_kw)

Bases: PlotWidget

property cb: ItoolColorBarItem

set_dimensions(width=30, horiz_pad=None, vert_pad=None, font_size=11.0)

setVisible(visible)