ImageTool Manager

ImageToolManager window screenshot ImageToolManager window screenshot

ImageToolManager is the workspace for a full ImageTool analysis session. It keeps top-level ImageTool rows (ImageTools that are not child rows), tools opened from those ImageTools, and ImageTool windows opened from those tools in one tree. The manager also shows when a row created by another row needs to be updated because the ImageTool or tool that created it changed, and it can show code that repeats the selected steps in a notebook or script.

Why use the manager?

  • Launch and watch many ImageTool windows simultaneously without interrupting your notebook or script.

  • Keep nested ImageTool windows organized in a tree that shows their relationships and provenance.

  • Update tools and ImageTool windows when the ImageTool or tool that created them changes.

  • Link multiple ImageTools, duplicate them, or update their data in place in case of real-time data acquisition.

  • Save multiple windows and full hierarchies to a file, share them with collaborators, and reload them later to pick up right where you left off.

  • Synchronize directly with Jupyter via %watch, access data from scripts using fetch, copy code that repeats GUI steps, and perform quick analyses in the GUI through a built-in IPython console.

  • Drag-and-drop files to open them quickly, or use the integrated data explorer to browse preview data.

Starting the manager

  • If you have a Python environment with ERLabPy installed:

    Run itool-manager in a terminal or command prompt window in the environment where ERLabPy is installed.

  • You can also install the manager as an application on your operating system. See Installing as a standalone application for instructions.

Note

Opening an ImageTool window for the very first time after installing may take a couple of minutes as caches are built. Subsequent launches will be much faster.

Opening and replacing ImageTool windows

Once the manager is running, you can open ImageTools in several ways:

  • xarray.DataArray.qshow() or erlab.interactive.imagetool.itool() with manager=True sends windows to the only live manager or to the default manager for the current Python process. Pass an integer to target a specific manager index:

    data.qshow(manager=True)
data.qshow(manager=1)
eri.itool([d1, d2], manager=True, replace=[1, 2])

    Pass replace= to update data in existing windows instead of creating new ones.

  • ImageTool’s %itool magic command with the --manager (or -m) flag in an IPython session or Jupyter notebook.

    %itool -m darr
%itool -m 1 darr

  • The File → Move to Manager (Ctrl+Shift+M) action from an ImageTool window opened outside the manager. This action moves the active ImageTool to the manager.

  • Use the manager’s File → Add Data Files… action to load data in a new ImageTool.

  • Drag and drop supported ARPES data into the manager window.

    In the dialog that appears, you can choose the plugin to use for loading the data. For plugin loaders, expand Loader Extensions to set literal erlab.io.extend_loader() options. The name_map and coordinate_attrs rows also have buttons that inspect the first selected file and help build the literal values interactively.

    Hint

    For scans that are recorded across multiple files, drag and dropping any file in the scan will automatically load and concatenate the entire scan. If you want to load only the file you dropped, choose the plugin suffixed with Single File in the dialog.

  • Launch the built-in data explorer from File → Data Explorer or Ctrl+E when you want directory browsing and metadata preview before opening selected files in the manager. Use the loader options button next to the loader selector to apply the same loader_extensions= settings when opening selected files.

  • Watch notebook variables with the %watch magic to create windows that stay synchronized with your data structures. Use %watch -m 1 darr to watch into manager #1. See Notebook integration.

    Tip

    This is the recommended way when you are working in notebooks, because it keeps your workflow connected to your code and automatically synchronizes changes in both directions.

  • For custom integration with other workflows, scripts can call erlab.interactive.imagetool.manager.show_in_manager() or load_in_manager() directly (see Automation APIs).

When you open multiple DataArrays at once, the manager adds each window to the list without automatically showing them. To bring a window to the front, double-click its entry or select it and press Show.

Multiple manager instances

Multiple ImageTool Manager windows can run at the same time. The first live manager is manager #0, and later managers receive 0-based indexes in the order they start.

To start a new manager instance, choose File → New Manager Window from an existing manager window.

When more than one manager is running, either pass the index like manager=2 or set a default for the current Python process or notebook kernel:

import erlab.interactive.imagetool.manager as itm

itm.managers
itm.managers[1].use()
itm.managers[1].show(data)
data.qshow(manager=True)
other.qshow(manager=0)
%itool -m 1 data
%watch -m 1 data

The default is stored in the current session. The same actions are also available as IPython magics %manager list, %manager use 1, %manager current, and %manager clear.

If more than one manager is running and no default has been selected, calls that use manager=True raise an error instead of guessing.

Saving and loading

Windows in an ImageTool Manager instance can be saved to a workspace file (.itws), similar to how Igor Pro experiment files work. Pressing Ctrl+S in any child window saves the entire manager workspace, including all windows and their state.

File → Add Windows From Workspace… lets you choose windows from another workspace to import into the current manager.

Saved ImageTool workspaces can be reloaded via File → Open Workspace… (Ctrl+O) or by dragging the .itws file back into the manager to recreate your windows exactly as they were. Use File → Open Recent to reopen a recent workspace, or Clear Menu at the bottom of that submenu to remove the saved recent-workspace list. Share the file with collaborators and they will see the identical layout.

To check where the open manager is saved, choose File → Workspace Properties (Alt+Return). The dialog shows the associated workspace path, basic file status, whether there are unsaved changes, and the number of open ImageTool windows. Use its buttons to copy the path or reveal the .itws file in your system file browser.

Use File → Offload to Workspace to make the selected data lazy-loaded from the workspace file. This frees up memory but will slow down indexing and slicing. Use Dask → Load Into Memory in ImageTool to bring that data back into memory.

If the workspace contains watched notebook variables, the watched rows reopen with their variable-name badges. The rows stay disconnected until a notebook defines the matching variables and reconnects them, as described in Reconnecting watched rows.

Nested windows

When you are working in the manager, a new ImageTool window can appear as a child row under the tool or ImageTool that created it. A typical session looks like this:

  1. Open data in the manager, or watch a notebook variable, so it appears as an ImageTool row.

  2. Launch dtool, ktool, or another tool from that ImageTool.

  3. Use Open in ImageTool from that tool.

  4. The new ImageTool window appears under the tool or ImageTool that made it instead of as an unrelated top-level window.

That new ImageTool row remembers all of the information required to reproduce itself from the raw data. When its parent node updates, the manager can automatically mark it as out of date, update it, and show the steps and code in the side panel.

Choosing where new data opens

Many ImageTool transform dialogs accessible from menu actions use Result Placement to decide what happens to the transformed data:

  • Open Child Window creates a new ImageTool row as a child of the current ImageTool.

  • Open Top-Level Window creates a separate top-level ImageTool.

  • Replace Current overwrites the active ImageTool with the transformed data.

Automatic updates

When data changes in an ImageTool or tool, the tools and ImageTool windows it created may no longer match it. The manager shows this with badges:

  • Stale means the ImageTool or tool that created this row changed, and this row can probably be updated.

  • Unavailable means the manager cannot repeat the saved selection or operation on the current data, such as when a dimension, coordinate, or selection has changed too much.

  • Auto means the row is up to date and automatic updates are enabled.

Click the badge in the tree or the update banner inside the tool window to review the update. The Automatic Updates… dialog lets you apply a one-time update with Update Now, or turn automatic updates on or off and save that preference with Save. Saving only changes the automatic-update preference; it does not refresh the current window immediately.

Fitting tools can also take part in this flow. ftool, goldtool, and restool include Refit after update; when it is enabled, the tool reruns the same fit after compatible data from the ImageTool that opened it is updated.

Results from several ImageTools

Some manager results are made from two or more top-level ImageTools instead of from one parent row. Examples include Concatenate and console expressions such as tools[0] - tools[1].

The manager records the ImageTools that contributed to the result and shows their live relationship in the tree and side panel:

  • Changed means every recorded live input is still open, but at least one no longer matches the data or provenance that made the result.

  • Missing means at least one recorded live input was removed from the manager.

These badges describe the relationship to the currently open inputs. They do not mean the displayed result is invalid, and they do not change the result data automatically.

Reload Data also works on these results. If the live inputs are open, the manager uses their current data. If an input was removed but its recorded file source is still available, the manager reloads that input from the file before recomputing the result.

For results from console scripts, Reload Data replays the recorded code in the console if possible. Only reload derived results from workspaces you trust.

Operation history

Selecting a row fills the side panel with details about that item. For an ImageTool window created from another row, the panel can show:

  • The file(s) or data required to create the window

  • The steps used to create the selected ImageTool window

  • Code that can be pasted into a notebook or script to repeat those steps

Right-click on the steps list to copy code that rebuilds the data shown in the selected ImageTool window.

For watched variables, copied code contains the watched variable name. File-backed workflows also include a snippet that loads the data in the copied code. Otherwise, you will be prompted to enter the name of the variable to use as the source when you copy code.

Data Explorer and Console

In addition to ImageTool windows and analysis tools opened from them, the manager can also launch standalone apps that stay outside the tree view and workspace files.

Data Explorer

Open the explorer from File → Data Explorer or Ctrl+E.

Use it when you want to browse folders, preview metadata, queue batch loads, and then open selected files into the manager without writing code. For most day-to-day browsing it is faster than the interactive summary table in the I/O guide. Use erlab.io.summarize() instead when you want the overview as a DataFrame in Python or when you are developing loaders.

The explorer can also be launched standalone from Python or the command line for browsing and previewing. Opening selected files into ImageTool analysis still requires a running ImageTool manager, which is why launching it from the manager is the recommended path.

For the standalone tool page, see Data explorer.

Periodic Table

Open the periodic table from Apps → Periodic Table or Ctrl+Shift+P.

Use it when you want quick reference for core-level energies photoionization cross sections.

For the standalone tool page, see Periodic table.

Console

For quick calculations and data exploration without leaving the manager, the embedded IPython console is useful.

Toggle the embedded IPython console with Ctrl+J or via the View menu. The console exposes a tools list containing a provenance-aware handle for every ImageTool. These handles are not xarray.DataArray objects, but they support many of the same operations and keep track of the manager history. For example:

# Access the underlying DataArray of the first window
tools[0].data

# Inspect and access ImageTool children under the first window
tools[0].children

# Create an ImageTool containing the difference of the first two windows
tools[0] - tools[1]

# Use complicated expressions
tools[0].qsel(alpha=slice(-1, 1)).qsel.average("eV")
era.transform.rotate(tools[0], 2.0, axes=("alpha", "eV"), reshape=False)

# Use a child ImageTool in a similar calculation
tools[0].children[0] - tools[1]

# xarray module calls also keep manager inputs when they receive tool handles
xr.concat([tools[0], tools[1]], dim="scan")

# Simple helper functions defined in the console can receive tool handles directly
def normalize(data):
    return data / data.max()

normalize(tools[0])

# Keep the result in the console, then open it later
diff = tools[0] - tools[1]
diff.qshow(manager=True)

# Replace data in the first window
tools[0].data = tools[0].assign_coords(time=tools[1].time)

Run standard Python, %magic commands, or inspect objects with ? exactly as you would in a notebook.

Notebook integration

The manager keeps notebooks synchronized through the %watch magic and provides functions for retrieving and storing data.

Tip

If you are using VS Code (or other editor that supports VS Code extensions), the dedicated erlab extension ( marketplace | open-vsx ) adds convenient commands for working with the manager directly from notebooks. Search for erlab in the extensions panel of your editor to install it.

Watching notebook variables

Load the IPython extension and start watching variables:

%load_ext erlab.interactive
%watch my_data

Note

To load the extension automatically, add erlab.interactive to your IPython configuration, or configure VS Code’s Jupyter extension with

"jupyter.runStartupCommands": [
    "%load_ext erlab.interactive"
]

so %watch is always available.

Watching creates a labeled ImageTool window. Any time my_data changes in the notebook, the manager updates the matching window. Editing inside ImageTool—rotation, symmetrization, cropping, or other ImageTool operations—writes the results back to the notebook variable.

Note

To keep comparisons fast, only small subsets of large arrays are compared to check whether data has been modified. If a change slips by, re-run %watch my_data to force a refresh.

Controlling watches:

%watch data1 data2 data3   # add multiple variables
%watch                     # list watched names
%watch --restore           # reconnect saved watched rows by variable name
%watch -d data1 data2      # stop watching specific variables
%watch -x data1            # stop watching and close the window
%watch -z                  # stop watching everything
%watch -xz                 # stop watching and close every watched window

You can also right-click a tool in the manager and choose Stop Watching.

If a variable is deleted or replaced with a non-DataArray, the manager automatically breaks the link and keeps the window as a regular ImageTool.

Reconnecting watched rows

A watched row stores the variable name shown on its badge. If a notebook kernel stops, or if you close and reopen the manager workspace, the row stays in the manager but cannot synchronize until a notebook reconnects it. Disconnected watched rows keep their variable-name badge and show a disconnected tooltip in the manager.

To reconnect one variable after restarting a notebook kernel:

  1. Run the notebook cells that create the DataArray.

  2. Run %watch my_data again.

The manager reuses the existing watched row for my_data instead of creating a duplicate. This also forces a refresh if the automatic change detector missed an update.

To reconnect every watched row in the open manager workspace:

%watch --restore

%watch --restore looks at the watched variable names saved in the open workspace and reconnects the rows whose names exist in the current notebook namespace as xarray.DataArray objects. Rows for variables that are missing, or variables that currently hold a different kind of object, stay disconnected.

To share a linked notebook and workspace with someone else:

  1. Save the manager workspace as a .itws file.

  2. Send both the .ipynb notebook and the .itws workspace.

  3. On the other computer, open the .itws file in ImageTool Manager.

  4. Run the notebook cells that create the watched variables.

  5. Run %watch --restore.

The notebook and workspace do not need to live in the same folder. The rows reconnect by the variable names saved in the workspace, so the receiving notebook must define matching DataArray variables such as my_data.

If several disconnected watched rows use the same variable name, %watch my_data and %watch --restore skip that name instead of guessing. Remove the extra watched links with Stop Watching, or use an editor integration that can reconnect a specific manager row.

Outside IPython (e.g., marimo notebooks)

If %watch is not available, use the Python API directly:

from erlab.interactive.imagetool.manager import watch

# Start watching a DataArray
watch("my_data")

# Stop watching one variable
watch("my_data", stop=True)

# Stop watching everything
watch(stop_all=True)

# Reconnect saved watched rows in the open manager workspace
watch(restore=True)

In non-IPython environments, watcher updates fall back to polling, which periodically checks for changes in the watched variables. You can adjust the frequency with poll_interval_s if needed:

watch("my_data", poll_interval_s=0.5)

Alternately, you can force an immediate check for changes with maybe_push instead of waiting for the next poll.

Use shutdown to stop threads cleanly.

Note

watch can infer a namespace automatically, but providing an explicit namespace= argument is safer when you call it indirectly (for example, from small utility functions, callbacks, or wrappers) where the caller scope may not be obvious. In those cases, pass the exact mapping you want to watch, like namespace=globals().

Accessing manager data programmatically

Use fetch inside a notebook or script to copy data out of the manager:

from erlab.interactive.imagetool.manager import fetch

data = fetch(0)  # returns an xarray.DataArray copy

Because fetch returns a copy, you can safely modify it without touching the live window.

Sharing data via %store

The %store magic can persist variables between notebook sessions. Select tools in the manager and run File → Store with IPython (or the matching context-menu command) to push their DataArray objects into the %store database. Internally, this executes:

my_data = tools[0].data
%store my_data

Later, in any notebook, retrieve the stored variable with %store -r my_data and continue analysis without reopening files.

Editor integration

If you are using VS Code (or other editor that supports VS Code extensions), the dedicated erlab extension ( marketplace | open-vsx ) adds convenient features for working with the manager directly from notebooks. Search for erlab in the extensions panel of your editor to install it.

Editor commands named Reconnect Watched Variables use the same restore workflow as %watch --restore: the notebook must define the watched xarray.DataArray variables, and the open manager workspace supplies the saved watched row names.

Automation APIs

If you wish to integrate the manager into custom workflows, you can programmatically load data and control ImageTool windows in the manager. Use the public functions exported from erlab.interactive.imagetool.manager:

from erlab.interactive.imagetool.manager import load_in_manager, replace_data, show_in_manager

# Open raw files and let the manager choose the loader interactively
load_in_manager(["scan1.pxt", "scan2.pxt"])

# Open raw files with temporary loader extensions
load_in_manager(
    ["scan1.pxt", "scan2.pxt"],
    "merlin",
    loader_extensions={"coordinate_attrs": ("scan_number",)},
)

# Open two ImageTools and link their cursors
show_in_manager([data_a, data_b], link=True, target=1)

# Replace the dataset at index 3 with a new result
replace_data(3, new_data, target=1)

Additional functions and objects such as managers, replace_data, watch, and manager_selection_info give you finer control when building custom acquisition pipelines or editor integrations.

Under the hood these functions communicate with the GUI via ZeroMQ. Manager discovery is stored in a user-scoped live registry, so normal routing is intended for Python processes running in the same user session as the manager. See the API docs for details.

Installing as a standalone application

Standalone bundles for Windows and macOS let you run the manager without managing a Python environment. They add OS-level conveniences such as opening supported files by double-clicking them (or, on macOS, dropping files onto the Dock icon). For macOS 26 and later, the app also features a dynamic icon that matches the new design language.

Download the latest release from the project’s releases page, then follow the platform-specific steps below. For other platforms, or if you prefer full control, build from source via Build from source.

Windows

  1. Download the latest Windows build .zip file from the releases page.

  2. Extract it and double-click the included .exe installer, then follow the prompts.

macOS

  1. Download the latest .zip archive that matches your architecture from the releases page.

  2. Extract it to obtain ImageTool Manager.app.

  3. Move the app into /Applications (or any folder you prefer) and launch it like any other macOS application.

Linux and source-built bundles

Official standalone release bundles are currently only provided for Windows and macOS. Linux users can build from source (see Build from source), and the resulting app can be launched directly from the build folder. For a more integrated experience, you can create a desktop entry or alias that points to the built executable. If you want supported builds for Linux, please submit an issue to let us know!

Updating the application

Updates can be checked and installed from within the application itself. Select Check for Updates in the menu bar under Help (Windows) or ImageTool Manager next to (macOS) and follow the prompts.

Build from source

If you want to build the standalone application from source due to platform compatibility or other reasons, follow these steps:

  1. Clone the repository:

    git clone https://github.com/kmnhan/erlabpy.git
cd erlabpy

  2. Install dependencies (requires uv):

    uv sync --all-extras --group pyinstaller --group pyqt6

  3. Build the application:

    uv run pyinstaller manager.spec

  4. The resulting app will be in dist/ImageTool Manager.

  5. (Optional, Windows only) Install Inno Setup and add to your system PATH. Then run iscc manager.iss to create an installer file.