ImageTool Manager

ImageToolManager keeps large analysis sessions organized. It tracks every ImageTool window, preview, and metadata entry in a single tree view so you can link, archive, and share them without juggling dozens of floating windows.

Why use the manager?

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

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

• Save and reopen complete workspaces, including colormaps, cursor positions, window geometry, and ROIs.

• Archive rarely used windows to disk so they can be restored later without consuming RAM.

• Synchronize directly with Jupyter via %watch, access data from scripts using fetch, and perform quick analyses 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

• Only one manager can run per machine.

• 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 directly to the manager:

  data.qshow(manager=True)
  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
  

• 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 → Open File… 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.

  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. Browse arbitrary folders, preview metadata, and open selected files in the manager.

• Watch notebook variables with the %watch magic to create windows that stay synchronized with your data structures. See Notebook integration.

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

Navigating and organizing tools

The left pane lists every ImageTool window by index and optional name (index: name). Selecting entries populates the right pane with metadata and a live preview.

Note

Enable View → Preview on Hover to see thumbnails while moving the mouse over the list.

The following lists common actions included in the File, Edit, and right-click context menus:

• Show / Hide / Remove – Use the toolbar buttons or Return, Ctrl+W, and Del to bring windows to the front, hide them, or remove them entirely. These controls live in File.

  Note

  Ctrl+W and Del also works when analysis windows are focused, which is often more convenient than switching back to the manager.

• Rename / Duplicate – Rename multiple selections at once or activate in-place editing for a single tool. Duplicate clones the currently selected windows, including their state.

• Reset Index – Renumbers all windows from zero.

• Link / Unlink – Ctrl+L links the selected windows so they share cursors and slices; Ctrl+Shift+L removes the links.

• Archive / Unarchive – Archive writes a tool’s dataset and UI state to a temporary file, frees its memory, and grays it out in the list. Unarchive reopens it. Both actions are under File.

• Concatenate – Combine selected data with xarray.concat() and open the result in a new ImageTool window.

• Reload Data – Re-fetches data from disk using the original loader function. Handy when data is updated during acquisition.

Icons next to each entry indicate special states: linked windows share a colored badge, chunked Dask arrays show the dask icon, and watched variables display their notebook name. Right-click to see all context-sensitive actions.

Workspaces

Choose File → Save Workspace As… to save multiple open windows to a single .itws file. Workspaces store not only the data, but also the ImageTool settings such as cursor locations, colormaps, window geometry, and ROIs.

Saved ImageTool workspaces can be reloaded via File → Open Workspace… or by dragging the .itws file back into the manager to recreate your windows exactly as they were. Share the file with collaborators and they will see the identical layout.

Built-in explorer and console

• Data Explorer – The explorer window (File → Data Explorer or Ctrl+E) provides a filesystem browser tailored for ARPES datasets. Preview metadata, queue batch loads, or open entire directories as tabs.

• Console – Toggle the embedded IPython console with Ctrl+J or via the View menu. The console exposes a tools list containing wrappers for every ImageTool. For example:

  # List names of all windows
  [tool.name for tool in tools]
  
  # Access the underlying DataArray of the first window
  tools[0].data
  
  # Replace data in the first window
  tools[0].data = new_data
  

  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 exposes helper APIs 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 -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.

Note

When a notebook kernel shuts down, watched windows remain open in the manager but no longer synchronize. Use Stop Watching or run %watch -z before closing the kernel to avoid confusion. Variables watched from different notebooks are color-coded for clarity.

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)

In non-IPython environments, watcher updates falls 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 helper 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.

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 helpers exported from erlab.interactive.imagetool.manager:

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

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

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

# Replace the dataset at index 3 with a new result
show_in_manager(new_data, replace=3)

Additional functions such as replace_data and watch give you finer control when building custom acquisition pipelines.

Under the hood these helpers communicate with the GUI via ZeroMQ, so they can be called from any Python process that can reach the manager (even on a different machine). 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.

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.