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 managers using ZeroMQ connections. The first manager uses the default request port 45555 and watch port 45556 when those ports are free; additional managers use dynamically assigned ports and can be selected by 0-based manager index.

Functions

clear_default_manager()	Clear the default ImageTool manager for this Python process.
fetch(index, *[, target])	Get data from the ImageTool window at the given index.
get_default_manager(*[, validate])	Return the default ImageTool manager for this Python process.
get_log_file_path()	Return the path to the log file used by ImageTool Manager.
is_running([target])	Check whether an instance of ImageToolManager is active.
load_in_manager(paths[, loader_name, target])	Load and display data in the ImageToolManager.
main([execute])	Start the ImageToolManager application.
manager_selection_info()	Return manager selection state for external clients.
maybe_push(*[, shell, namespace])	Push changed variables to manager for a given shell or namespace.
replace_data(index, data, *[, target])	Replace data in existing ImageTool windows.
set_default_manager(index)	Set the default ImageTool manager for this Python process.
show_in_manager(data[, target])	Create and display ImageTool windows in the ImageToolManager.
shutdown(*[, shell, namespace, remove])	Shutdown watcher for a namespace and unregister associated hooks.
use_manager(index)	Temporarily set the default ImageTool manager.
watch(*varnames[, shell, namespace, stop, ...])	Watch namespace variables and synchronize them with ImageTool manager.
watch_info(*[, target])	Return watched-variable metadata for the target manager.
watched_variables(*[, shell, namespace])	Return currently watched variable names for the selected namespace.

Classes

ImageToolManager()	The ImageToolManager window.
ImageToolManagerHandle(*, index, pid, host, ...)	Handle for a live ImageTool manager.
ImageToolManagerRegistry()	Live ImageTool manager registry.

Exceptions

ImageToolManagerAmbiguousError	Raised when a client operation needs an explicit manager target.
ImageToolManagerNotFoundError	Raised when a requested manager target is not available.

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, watched_workspace_link_id=None, watched_source_label=None, watched_connected=True, source_input_ndim=None, source_input_dtype=None, uid=None, provenance_spec=None, source_spec=None, source_auto_update=False, source_state='fresh', index=None)

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.

compact_workspace()

Rewrite the current workspace file to remove unused space.

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.

import_workspace(*, native=True)

Import selected windows from another workspace file.

index_from_slicer_area(slicer_area)

Get the index corresponding to the given slicer area.

property is_workspace_modified: bool

Return whether this workspace has unsaved restorable changes.

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)

Replace this manager with a workspace file.

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

Open another ImageTool Manager process.

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 workspace document.

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.

save_as(*, native=True)

Save the current workspace under a new path and bind to that path.

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.

property workspace_path: str | None

Path of the workspace document associated with this manager.

wrapper_from_slicer_area(slicer_area)

Get the ImageTool wrapper corresponding to the given slicer area.

exception erlab.interactive.imagetool.manager.ImageToolManagerAmbiguousError

Bases: RuntimeError

Raised when a client operation needs an explicit manager target.

class erlab.interactive.imagetool.manager.ImageToolManagerHandle(*, index, pid, host, port, watch_port, started, version, workspace_path=None, is_default=False)

Bases: object

Handle for a live ImageTool manager.

property endpoint: str

Request endpoint used by this manager.

fetch(index)

Fetch ImageTool data from this manager.

load(paths, loader_name=None, **load_kwargs)

Load files into this manager.

replace(index, data)

Replace ImageTool data in this manager.

show(data, **kwargs)

Create ImageTool windows in this manager.

use()

Set this manager as the default for the current Python process.

watch(*varnames, **kwargs)

Watch variables in this manager.

watch_info()

Return watched-variable metadata for this manager.

index: int

pid: int

host: str

port: int

watch_port: int

started: str

version: str

workspace_path: str | None

is_default: bool

exception erlab.interactive.imagetool.manager.ImageToolManagerNotFoundError

Bases: RuntimeError

Raised when a requested manager target is not available.

class erlab.interactive.imagetool.manager.ImageToolManagerRegistry

Bases: object

Live ImageTool manager registry.

The registry is a lightweight view over the live manager registry. It refreshes whenever it is displayed, iterated, or indexed.

Added in version 3.22.0.

items()

Return (index, handle) pairs for live managers.

keys()

Return live manager indexes.

values()

Return live manager handles.

erlab.interactive.imagetool.manager.clear_default_manager()

Clear the default ImageTool manager for this Python process.

erlab.interactive.imagetool.manager.fetch(index, *, target=None)

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

• target (int | None, default: None) – Optional 0-based manager index. If omitted, the current process default is used. If no default is set, the only live manager is used. If multiple managers are live, an ambiguity error is raised.

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.

• versionchanged:: 3.22.0 – Added the target argument for selecting a manager by index.

Return type:

DataArray | None

erlab.interactive.imagetool.manager.get_default_manager(*, validate=True)

Return the default ImageTool manager for this Python process.

Parameters:

validate (bool, default: True) – If True, clear and return None when the saved default no longer points to a live manager.

Returns:

int or None – The default 0-based manager index, or None if no default is set.

Return type:

int | 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(target=None)

Check whether an instance of ImageToolManager is active.

Parameters:

target (int | None, default: None) – Optional 0-based manager index to check. If omitted, return True when any manager is live.

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, *, target=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.

• target (int | None, default: None) – Optional 0-based manager index. If omitted, the current process default is used. If no default is set, the only live manager is used. If multiple managers are live, an ambiguity error is raised.

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

Returns:

Response or None – Manager response for socket calls. Returns None when the manager is in the same Python process and the data is passed directly.

Return type:

Response | None

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

Return manager selection state for external clients.

Returns:

dict – JSON-serializable dictionary with live manager records, the current default index, the resolved index when one can be selected without prompting, a needs_selection flag, and a reason string. The reason is one of "none", "single", "default", or "multiple".

Return type:

dict[str, object]

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, *, target=None)

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.

• target (int | None, default: None) – Optional 0-based manager index. If omitted, the current process default is used. If no default is set, the only live manager is used. If multiple managers are live, an ambiguity error is raised.

Returns:

• Response – Manager response.

• versionchanged:: 3.22.0 – Added the target argument for selecting a manager by index.

Return type:

Response

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

Set the default ImageTool manager for this Python process.

Parameters:

index (int) – 0-based manager index from erlab.interactive.imagetool.manager.managers.

Returns:

int – The selected manager index.

Raises:

ValueError – If index is negative or no live manager has that index.

Return type:

int

erlab.interactive.imagetool.manager.show_in_manager(data, target=None, **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.

• target (int | None, default: None) – Optional 0-based manager index. If omitted, the current process default is used. If no default is set, the only live manager is used. If multiple managers are live, an ambiguity error is raised.

• 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.

Returns:

Response or None – Manager response for socket calls. Returns None when the manager is in the same Python process and the data is passed directly.

Return type:

Response | None

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.use_manager(index)

Temporarily set the default ImageTool manager.

Parameters:

index (int) – 0-based manager index to use inside the context.

erlab.interactive.imagetool.manager.watch(*varnames, shell=None, namespace=None, stop=False, remove=False, stop_all=False, restore=False, target=None, source_label=None, 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.

• restore (bool, default: False) – If True, reconnect watched variables stored in the selected ImageTool manager workspace when variables with matching names exist in the namespace.

• target (int | None, default: None) – Optional 0-based ImageTool manager index to watch into. If omitted, the current process default is used. If no default is set, the only live manager is used. If multiple managers are live, an ambiguity error is raised.

• source_label (str | None, default: None) – Optional integration-supplied notebook/source label used to disambiguate saved watched rows. Regular notebook users do not need to set this.

• 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.

• versionchanged: (..) – 3.22.0: Added restore and stable workspace-linked watched variables so saved manager workspaces can reconnect to notebook variables by name.

Returns:

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

Return type:

tuple[str, …]

erlab.interactive.imagetool.manager.watch_info(*, target=None)

Return watched-variable metadata for the target manager.

This is primarily intended for editor integrations and the watcher restore workflow.

Added in version 3.22.0.

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, …]