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: _ImageToolManagerBase

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

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

add_imagetool(tool, *, show=True, activate=False, watched_var=None, watched_workspace_link_id=None, watched_source_label=None, watched_source_uid=None, watched_connected=True, source_input_ndim=None, source_input_dtype=None, uid=None, provenance_spec=None, source_spec=None, source_binding=None, source_auto_update=False, source_state='fresh', index=None, snapshot_token=None, created_time=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_binding=None, source_auto_update=False, source_state='fresh', output_id=None, snapshot_token=None, created_time=None)

add_widget(widget)

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

compact_workspace()

concat_selected()

dependency_input_summary_for_uid(uid)

dependency_status_badge_for_uid(uid)

dependency_status_for_uid(uid)

dependency_status_label_for_uid(uid)

dependency_status_tooltip_for_uid(uid)

dragEnterEvent(event)

dropEvent(event)

duplicate_childtool(uid)

duplicate_imagetool(index)

duplicate_selected()

ensure_console_initialized()

ensure_explorer_initialized()

event(event)

eventFilter(obj=None, event=None)

garbage_collect()

Run garbage collection to free up memory.

get_childtool(uid)

hide_all()

hide_selected()

import_workspace(*, native=True)

index_from_slicer_area(slicer_area)

property is_workspace_modified: bool

label_of_imagetool(index)

link_imagetools(*indices, link_colors=True)

link_selected(link_colors=True, deselect=True)

linker_index(linker)

load(*, native=True)

name_of_imagetool(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.

offload_selected_to_workspace()

offload_to_workspace(targets, *, native=True)

open(*, native=True)

open_log_directory()

open_multiple_files(queued, try_workspace=False)

open_new_manager_instance()

open_recent_workspace(fname)

open_settings()

promote_child_imagetool(uid)

promote_selected()

reindex()

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

reload_selected()

remove_all_tools()

Remove all ImageTool windows.

remove_imagetool(index, *, update_view=True)

Remove the ImageTool window corresponding to the given index.

remove_selected()

rename_imagetool(index, new_name)

rename_selected()

save(*, native=True)

save_as(*, native=True)

show_childtool(uid)

show_explorer()

show_imagetool(index)

Show the ImageTool window corresponding to the given index.

show_ptable()

show_selected()

show_selected_source_updates()

show_workspace_properties()

store_selected()

target_from_slicer_area(slicer_area)

toggle_console()

unlink_selected(deselect=True)

unwatch_selected()

updated(old_version, new_version)

property workspace_path: str | None

wrapper_from_slicer_area(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.

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.

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.

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