erlab.interactive.imagetool.manager

Manager for multiple ImageTool windows.

This module provides a GUI application for managing multiple ImageTool windows. The application can be started by running the script itool-manager from the command line in the environment where the package is installed.

Python scripts communicate with the manager using a ZeroMQ connection with the default port number 45555. The port number can be changed by setting the environment variable ITOOL_MANAGER_PORT.

Functions

fetch(index)	Get data from the ImageTool window at the given index.
get_log_file_path()	Return the path to the log file used by ImageTool Manager.
is_running()	Check whether an instance of ImageToolManager is active.
load_in_manager(paths[, loader_name])	Load and display data in the ImageToolManager.
main([execute])	Start the ImageToolManager application.
maybe_push(*[, shell, namespace])	Push changed variables to manager for a given shell or namespace.
replace_data(index, data)	Replace data in existing ImageTool windows.
show_in_manager(data, **kwargs)	Create and display ImageTool windows in the ImageToolManager.
shutdown(*[, shell, namespace, remove])	Shutdown watcher for a namespace and unregister associated hooks.
watch(*varnames[, shell, namespace, stop, ...])	Watch namespace variables and synchronize them with ImageTool manager.
watched_variables(*[, shell, namespace])	Return currently watched variable names for the selected namespace.

Classes

ImageToolManager()

The ImageToolManager window.

class erlab.interactive.imagetool.manager.ImageToolManager

Bases: QMainWindow

The ImageToolManager window.

This class implements a GUI application for managing multiple ImageTool windows.

Users do not need to create an instance of this class directly. Instead, use the command line script itool-manager or the function main to start the application.

Signals:

sigLinkersChanged() – Signal emitted when the linker state is changed.

about()

Show the about dialog.

add_childtool(tool, index, *, show=True, uid=None)

Register a child tool window.

This is mainly used for handling tool windows such as goldtool and dtool opened from child ImageTool windows.

Parameters:

• tool (ToolWindow) – The tool window to add.

• index (int | str) – Target of the parent managed window.

• show (bool, default: True) – Whether to show the tool window after adding it, by default True.

add_imagetool(tool, *, show=True, activate=False, watched_var=None, source_input_ndim=None, source_input_dtype=None, uid=None, provenance_spec=None, source_spec=None, source_auto_update=False, source_state='fresh')

Add a new ImageTool window to the manager and show it.

Parameters:

• tool (ImageTool) – ImageTool object to be added.

• show (bool, default: True) – Whether to show the window after adding, by default True.

• activate (bool, default: False) – Whether to focus on the window after adding, by default False.

• watched_var (tuple[str, str] | None, default: None) – If the tool is created from a watched variable, this should be a tuple of the variable name and its unique ID.

• source_input_ndim (int | None, default: None) – Original dimensionality of the bound source before ImageTool-specific promotion (for example, promoted 1D inputs).

Returns:

int – Index of the added ImageTool window.

Return type:

int

add_imagetool_child(tool, parent, *, show=True, activate=False, uid=None, provenance_spec=None, source_spec=None, source_auto_update=False, source_state='fresh', output_id=None)

add_widget(widget)

Save a reference to an additional window widget.

This is mainly used for handling tool windows such as goldtool and dtool opened from child ImageTool windows. This way, they can stay open even when the ImageTool that opened them is archived or removed.

All additional windows are closed when the manager is closed.

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

Parameters:

widget (QWidget) – The widget to add.

archive_selected()

Archive selected ImageTool windows.

property cache_dir: str

Name of the cache directory where archived data are stored.

check_for_updates()

closeEvent(event)

Handle proper termination of resources before closing the application.

color_for_linker(linker)

Get the color that should represent the given linker.

color_for_watched_var_kernel(kernel_uid)

Return a different color for different source kernels.

concat_selected()

Concatenate the selected data using xarray.concat().

dragEnterEvent(event)

Handle drag-and-drop operations entering the window.

dropEvent(event)

Handle drag-and-drop operations dropping files into the window.

duplicate_childtool(uid)

Duplicate the child tool corresponding to the given UID.

Parameters:

uid (str) – UID of the child tool to duplicate.

Returns:

str – UID of the newly created child tool.

Return type:

str

duplicate_imagetool(index)

Duplicate the ImageTool window corresponding to the given index.

Parameters:

index (int | str) – Index of the ImageTool window to duplicate.

Returns:

int – Index of the newly created ImageTool window.

Return type:

int | str

duplicate_selected()

Duplicate selected windows.

ensure_console_initialized()

Ensure that the console window is initialized.

ensure_explorer_initialized()

Ensure that the data explorer window is initialized.

eventFilter(obj=None, event=None)

Event filter that intercepts select all and copy shortcuts.

For some operating systems, shortcuts are often intercepted by actions in the menu bar. This filter ensures that the shortcuts work as expected when the target widget has focus.

property explorer: _TabbedExplorer

garbage_collect()

Run garbage collection to free up memory.

get_childtool(uid)

Get the child tool window corresponding to the given UID.

Parameters:

uid (str) – The unique ID of the child tool to get.

Returns:

ToolWindow – The child tool window corresponding to the given UID.

Return type:

ToolWindow

get_imagetool(index, unarchive=True)

Get the ImageTool object corresponding to the given index.

Parameters:

• index (int | str) – Index of the ImageTool window to retrieve.

• unarchive (bool, default: True) – Whether to unarchive the tool if it is archived, by default True. If set to False, an error will be raised if the tool is archived.

Returns:

ImageTool – The ImageTool object corresponding to the index.

Return type:

ImageTool

hide_all()

Hide all windows.

hide_selected()

Hide selected windows.

index_from_slicer_area(slicer_area)

Get the index corresponding to the given slicer area.

label_of_imagetool(index)

Get the label of the ImageTool window corresponding to the given index.

link_imagetools(*indices, link_colors=True)

Link the ImageTool windows corresponding to the given indices.

link_selected(link_colors=True, deselect=True)

Link selected ImageTool windows.

load(*, native=True)

Load the state of the manager from a file.

Parameters:

native (bool, default: True) – Whether to use the native file dialog, by default True. This option is used when testing the application to ensure reproducibility.

name_of_imagetool(index)

Get the name of the ImageTool window corresponding to the given index.

property next_idx: int

Index for the next window.

node_from_slicer_area(slicer_area)

property ntools: int

Number of ImageTool windows being handled by the manager.

open(*, native=True)

Open files in a new ImageTool window.

Parameters:

native (bool, default: True) – Whether to use the native file dialog, by default True. This option is used when testing the application to ensure reproducibility.

open_log_directory()

Open the log directory in the system file explorer.

open_multiple_files(queued, try_workspace=False)

Open multiple files in the manager.

open_settings()

Open the settings dialog for the ImageTool manager.

promote_child_imagetool(uid)

Promote the nested ImageTool identified by uid to a top-level row.

promote_selected()

Promote the selected nested ImageTool to a top-level window.

property ptable_window: PeriodicTableWindow

reindex()

Reset indices of ImageTool windows to be consecutive in displayed order.

reload_selected()

Reload data in selected ImageTool windows.

remove_all_tools()

Remove all ImageTool windows.

remove_imagetool(index, *, update_view=True)

Remove the ImageTool window corresponding to the given index.

remove_selected()

Discard selected ImageTool windows.

rename_imagetool(index, new_name)

Rename the ImageTool window corresponding to the given index.

rename_selected()

Rename selected ImageTool windows.

save(*, native=True)

Save the current state of the manager to a file.

Parameters:

native (bool, default: True) – Whether to use the native file dialog, by default True. This option is used when testing the application to ensure reproducibility.

show_childtool(uid)

Show the child tool window corresponding to the given UID.

show_explorer()

Show data explorer window.

show_imagetool(index)

Show the ImageTool window corresponding to the given index.

show_ptable()

Show the periodic-table explorer window.

show_selected()

Show selected windows.

show_selected_source_updates()

Show automatic update controls for the selected child window.

store_selected()

target_from_slicer_area(slicer_area)

toggle_console()

Toggle the console window.

unarchive_selected()

Unarchive selected ImageTool windows.

unlink_selected(deselect=True)

Unlink selected ImageTool windows.

unwatch_selected()

Unwatch selected ImageTool windows.

updated(old_version, new_version)

Notify the user that the application has been updated.

wrapper_from_slicer_area(slicer_area)

Get the ImageTool wrapper corresponding to the given slicer area.

erlab.interactive.imagetool.manager.fetch(index)

Get data from the ImageTool window at the given index.

Parameters:

index (int | str) – Index of the ImageTool window to get data from, or the unique identifier (UID) of a watched variable (used internally).

Returns:

xr.DataArray or None – The data in the ImageTool window at the given index, or None if the index is invalid or the data cannot be retrieved.

Return type:

DataArray | None

erlab.interactive.imagetool.manager.get_log_file_path()

Return the path to the log file used by ImageTool Manager.

erlab.interactive.imagetool.manager.is_running()

Check whether an instance of ImageToolManager is active.

Returns:

bool – True if an instance of ImageToolManager is running, False otherwise.

Return type:

bool

erlab.interactive.imagetool.manager.load_in_manager(paths, loader_name=None, **load_kwargs)

Load and display data in the ImageToolManager.

Parameters:

• paths (Iterable[str | PathLike]) – List of paths containing the data to be displayed in the ImageTool window.

• loader_name (str | None, default: None) – Name of the loader to use to load the data. The loader must be registered in erlab.io.loaders.

• **load_kwargs – Additional keyword arguments passed onto the load method of the loader.

erlab.interactive.imagetool.manager.main(execute=True)

Start the ImageToolManager application.

Running itool-manager from a shell will invoke this function.

erlab.interactive.imagetool.manager.maybe_push(*, shell=None, namespace=None)

Push changed variables to manager for a given shell or namespace.

In IPython kernels with post_run_cell support, this is usually not required because pushes are triggered automatically after each cell. In environments that rely on polling (for example, marimo), this can be used to force an immediate check outside the polling cadence.

Parameters:

• shell (_ShellProtocol | None, default: None) – Shell-like object exposing user_ns. This takes precedence over namespace when both are given.

• namespace (MutableMapping[str, Any] | None, default: None) – Namespace mapping used only when shell is not provided. By default, marimo kernel globals are used when running in marimo; otherwise the caller module globals are used if no IPython shell is detected.

erlab.interactive.imagetool.manager.replace_data(index, data)

Replace data in existing ImageTool windows.

Parameters:

• index (int | str | Collection[int | str]) – Index or indices of the ImageTool windows to replace data in. If data corresponds to a single ImageTool window, for instance a single DataArray, index is allowed to be a single integer. If data corresponds to multiple ImageTool windows, for instance a list of DataArrays, index must be a list of integers with the same length as data. All indices must be valid indices of existing ImageTool windows.

• data (Collection[DataArray | ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]] | DataArray | ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]] | Dataset | DataTree) – Data to replace the existing data in the ImageTool windows. See itool for more information.

erlab.interactive.imagetool.manager.show_in_manager(data, **kwargs)

Create and display ImageTool windows in the ImageToolManager.

Parameters:

• data (Collection[DataArray | ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]] | DataArray | ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]] | Dataset | DataTree | None) – The data to be displayed in the ImageTool window. See itool for more information.

• link – Whether to enable linking between multiple ImageTool windows, by default False.

• link_colors – Whether to link the color maps between multiple linked ImageTool windows, by default True.

• **kwargs – Keyword arguments passed onto ImageTool.

erlab.interactive.imagetool.manager.shutdown(*, shell=None, namespace=None, remove=False)

Shutdown watcher for a namespace and unregister associated hooks.

This removes IPython post_run_cell callbacks when present and stops fallback polling threads used in non-IPython environments.

Parameters:

• shell (_ShellProtocol | None, default: None) – Shell-like object exposing user_ns. This takes precedence over namespace when both are given.

• namespace (MutableMapping[str, Any] | None, default: None) – Namespace mapping used only when shell is not provided. By default, marimo kernel globals are used when running in marimo; otherwise the caller module globals are used if no IPython shell is detected.

• remove (bool, default: False) – If True, remove watched variables from manager while shutting down.

erlab.interactive.imagetool.manager.watch(*varnames, shell=None, namespace=None, stop=False, remove=False, stop_all=False, poll_interval_s=0.25)

Watch namespace variables and synchronize them with ImageTool manager.

Target resolution follows a shell-first policy:

1. If shell is provided, shell.user_ns is always used.

2. Else if namespace is provided, that mapping is used.

3. Else, try the active IPython shell.

4. If no IPython shell is available, use marimo kernel globals when running in marimo; otherwise fall back to the caller module globals.

In most cases, simply using watch("varname") without specifying shell or namespace should work as expected in both IPython and regular Python scripts.

Synchronization behavior differs by environment:

• IPython kernels that expose a post_run_cell event use that event hook to detect outbound variable changes, so synchronization is done immediately after each cell execution.

• Other environments (for example, marimo or plain Python namespaces) use a background polling thread to detect outbound changes. The polling interval can be configured with poll_interval_s. When using polling, changes are pushed to the manager at most once per poll_interval_s seconds.

For inbound updates from the ImageTool manager, shells that expose kernel.io_loop (typical IPython kernels) schedule namespace mutation on the kernel event loop. Other shells apply updates directly on the watcher thread.

Parameters:

• *varnames (str) – Variable names to watch or stop watching.

• shell (_ShellProtocol | None, default: None) – Shell-like object exposing user_ns. This takes precedence over namespace when both are given.

• namespace (MutableMapping[str, Any] | None, default: None) – Namespace mapping used only when shell is not provided. By default, marimo kernel globals are used when running in marimo; otherwise the caller module globals are used if no IPython shell is detected.

• stop (bool, default: False) – If True, stop watching specified variables.

• remove (bool, default: False) – If True, remove watched variables from manager while stopping.

• stop_all (bool, default: False) – If True, stop watching all variables in the namespace.

• poll_interval_s (float, default: 0.25) – Polling interval in seconds for fallback polling when post-run hooks are unavailable (for example, non-IPython environments). Must be greater than 0. This value is ignored when a post-run callback is successfully registered.

Returns:

tuple of str – Currently watched variable names after applying the operation.

Return type:

tuple[str, …]

erlab.interactive.imagetool.manager.watched_variables(*, shell=None, namespace=None)

Return currently watched variable names for the selected namespace.

Target resolution uses the same shell-first policy as watch(): use shell.user_ns when shell is provided, otherwise use namespace. When neither is provided, the active IPython shell is used if available; otherwise caller globals are used.

Parameters:

• shell (_ShellProtocol | None, default: None) – Shell-like object exposing user_ns. This takes precedence over namespace when both are given.

• namespace (MutableMapping[str, Any] | None, default: None) – Namespace mapping used only when shell is not provided. By default, marimo kernel globals are used when running in marimo; otherwise the caller module globals are used if no IPython shell is detected.

Returns:

tuple of str – Names of currently watched variables.

Return type:

tuple[str, …]