erlab.interactive.imagetool¶

Interactive visualization tool for multidimensional image-like data.

Modules¶

`core`	Provides core functionality of ImageTool.
`slicer`	Helper functions for fast slicing `xarray.DataArray` objects.
`fastslicing`	Numba-compiled functions for fast slicing of 2D, 3D, and 4D arrays.
`fastbinning`	Fast parallelized averaging for multidimensional arrays.
`controls`	Widgets for controlling `erlab.interactive.imagetool.core.ImageSlicerArea`.
`dialogs`	Dialogs for data manipulation found in the menu bar.
`manager`	Manager for multiple ImageTool windows.

Functions

itool(data, *[, link, link_colors, manager, ...])

Create and display ImageTool windows.

Classes

`BaseImageTool`([data, parent])	Base class for an ImageTool window.
`ImageTool`([data])	The ImageTool window class.

class erlab.interactive.imagetool.BaseImageTool(data=None, parent=None, **kwargs)[source]¶

Bases: QMainWindow

Base class for an ImageTool window.

This class combines the ImageSlicerArea and the controls into a single window.

Use this class only if you want to extend ImageTool without the menubar or keyboard shortcuts. Otherwise, use ImageTool.

Parameters:

data (default: None) – The data to be displayed.
parent (QWidget | None, default: None) – The parent widget.
**kwargs – Additional keyword arguments to the underlying ImageSlicerArea.

property array_slicer: ArraySlicer¶

class:ArraySlicer.

Type:: The underlying

closeEvent(evt)[source]¶

duplicate(**kwargs)[source]¶

Create a duplicate of the current ImageTool window.

This method creates a new instance of the ImageTool with the same data and state as the current one.

Parameters:: kwargs – Additional keyword arguments passed to the constructor of the new ImageTool.
Returns:: tool – The duplicated ImageTool window.
Return type:: Self

eventFilter(obj=None, event=None)[source]¶

classmethod from_dataset(ds, **kwargs)[source]¶

Restore a window from a dataset saved using to_dataset().

Parameters:

ds (Dataset) – The dataset.
**kwargs – Additional keyword arguments passed to the constructor.

classmethod from_file(filename, **kwargs)[source]¶

Restore a window from a file saved using to_file().

Parameters:

filename (str | PathLike) – The name of the file.
**kwargs – Additional keyword arguments passed to the constructor.

move_to_manager()[source]¶

property slicer_area: ImageSlicerArea¶

class:ImageSlicerArea.

Type:: The underlying

to_dataset()[source]¶

to_file(filename)[source]¶

Save the data, state, title, and geometry of the tool to a file.

The saved pickle file can be used to recreate the ImageTool with the class method from_pickle().

Parameters:: filename (str | PathLike) – The name of the pickle file.

widget_box(widget, **kwargs)[source]¶

Create a box that surrounds the given widget.

Parameters:

widget (QWidget) – The widget to be added to the box.
**kwargs – Additional keyword arguments passed to QGroupBox

Returns:

group – The created widget box.

Return type:

QGroupBox

class erlab.interactive.imagetool.ImageTool(data=None, **kwargs)[source]¶

Bases: BaseImageTool

The ImageTool window class.

This class adds the menubar with keyboard shortcuts to BaseImageTool. Use this class to create an ImageTool window.

Instead of instantiating this class directly, users should use the convenience function itool.

Parameters:

data (default: None) – The data to be displayed.
**kwargs – Additional keyword arguments to BaseImageTool.

Signals:

sigTitleChanged(str) – Emitted when the title of the window is changed by setting a new data or file. It is not emitted when the title is changed by other means such as setWindowTitle().

initialize_actions()[source]¶

property mnb: ItoolMenuBar¶

erlab.interactive.imagetool.itool(data, *, link=False, link_colors=True, manager=None, replace=None, execute=None, **kwargs)[source]¶

Create and display ImageTool windows.

This tool can also conveniently accessed with xarray.DataArray.qshow() and xarray.Dataset.qshow().

Parameters:

data (DataArray, Dataset, DataTree, numpy.ndarray, list of DataArray or list of numpy.ndarray) –
The data to be displayed. Data can be provided as:
- A xarray.DataArray with 2 to 4 dimensions
  
  The DataArray will be displayed in an ImageTool window.
- A numpy array with 2 to 4 dimensions
  
  The array will be converted to a DataArray and displayed in an ImageTool.
- A list of the above objects
  
  Multiple ImageTool windows will be created and displayed.
- A xarray.Dataset
  
  Every DataArray in the Dataset will be displayed across multiple ImageTool windows. Data variables that have less than 2 dimensions or more than 4 dimensions are ignored. Dimensions with length 1 are automatically squeezed.
- A xarray.DataTree
  
  Every leaf node will be parsed as a xarray.Dataset.
link (bool, default: False) – Whether to enable linking between multiple ImageTool windows when data is a sequence or a xarray.Dataset, by default False.
link_colors (bool, default: True) – Whether to link the color maps between multiple linked ImageTool windows, by default True. This argument has no effect if link is set to False.
manager (bool | None, default: None) –
Whether to open the ImageTool window(s) using the ImageToolManager if it is running. If not provided, the manager will only be used if it is in the same process as the caller.

Changed in version 3.4.0: Argument renamed from use_manager to manager.
replace (Collection[int] | int | None, default: None) –
When using the manager, this argument specifies which existing ImageTool windows should be replaced with the new data. If the manager is not used, this argument is ignored. replace can be set to:
- None (default):
  No existing windows are replaced. New windows are created for the new data.
- A single integer:
  - A valid index of an existing ImageTool window:
    The data in the window with the specified index is replaced with the new data.
  - A number that is greater by 1 than the largest existing index:
    A new ImageTool window is created with the new data. This is useful when you want to add a new window on initial execution, but want to replace the window with the same index on subsequent calls.
  - A negative integer:
    The index is interpreted as an index from the end of the list of existing ImageTool windows, sorted by their indices. For example, -1 refers to the window with the largest index, -2 to the second largest, and so on.
- A list of integers:
  A list of integers specifying the indices of the windows to be replaced, each of which is interpreted as described above. The length of the list must match the number of windows data is expected to create.
If this argument is used, the link, link_colors, and kwargs arguments are ignored, since no new windows are created.
execute (bool | None, default: None) –
Whether to execute the Qt event loop and display the window, by default None. For more information, see erlab.interactive.utils.setup_qapp().

This argument has no effect when the ImageTool window(s) are opened in the manager.
**kwargs – Additional keyword arguments to be passed onto the underlying slicer area. For a full list of supported arguments, see the erlab.interactive.imagetool.core.ImageSlicerArea documentation.

Returns:

ImageTool or list of ImageTool or None – The created ImageTool window(s).

If the window(s) are executed, the function will return None, since the event loop will prevent the function from returning until the window(s) are closed.

If the window(s) are not executed, for example while running in an IPython shell with %gui qt, the function will not block and return the ImageTool window(s) or a list of ImageTool windows depending on the input data.

The function will also return None if the windows are opened in the ImageToolManager.

Return type:

ImageTool | list[ImageTool] | None

Examples

>>> itool(data, cmap="gray", gamma=0.5)
>>> itool([data1, data2], link=True)