erlab.interactive.imagetool

Interactive visualization tool for multidimensional image-like data.

Modules

viewer	Provides core functionality of ImageTool.
viewer_linking	Linking and history decorators for ImageTool viewer widgets.
viewer_state	State and input parsing helpers for ImageTool viewer widgets.
slicer	Helper functions for fast slicing xarray.DataArray objects.
fastslicing	Helpers for fast slicing of 2D, 3D, and 4D arrays.
fastbinning	Fast parallelized averaging for multidimensional arrays.
controls	Widgets for controlling ImageTool slicers.
dialogs	Dialogs for data manipulation found in the menu bar.
manager	Manager for multiple ImageTool windows.
provenance	Public ImageTool provenance API.

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)

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)

property controls_visible: bool

Whether the ImageTool control docks are shown.

duplicate(**kwargs)

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)

classmethod from_dataset(ds, **kwargs)

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)

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()

property provenance_spec: ToolProvenanceSpec | None

Canonical replay provenance for the current ImageTool data.

set_provenance_spec(provenance_spec)

Set canonical replay provenance for the current ImageTool data.

property slicer_area: ImageSlicerArea

class:ImageSlicerArea.

Type:

The underlying

to_dataset()

to_file(filename)

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

The saved netcdf dataset can be used to recreate the ImageTool with the class method from_file().

Parameters:

filename (str | PathLike) – The name of the target netcdf file.

widget_box(widget, **kwargs)

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)

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()

property mnb: ItoolMenuBar

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

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

    If the Dataset contains multiple displayable DataArrays, ImageTool asks which variables to open. 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. If the DataTree contains multiple displayable DataArrays, ImageTool asks which variables to open, grouped by DataTree node path.

• 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 | int | None, default: None) –

  Whether to open the ImageTool window(s) using the ImageToolManager if it is running. An integer targets a specific 0-based manager index. If True, the current process default manager is used, or the only live manager if no default is set. If multiple managers are live and no default has been selected, an error is raised. 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.

  Changed in version 3.22.0: Integer manager indexes select a specific ImageTool Manager instance.

• 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: this can be a valid existing index (replace that window), one greater than the current largest index (create a new window), or a negative index from the end (for example, -1 means the largest existing index).

  • A list of integers: each integer is interpreted as described above. The list length 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.viewer.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)