ImageTool

Inspired by Image Tool for Igor Pro, developed by the Advanced Light Source at Lawrence Berkeley National Laboratory, ImageTool delivers the same efficient workflow, now enhanced by xarray and Python.

Key capabilities

• Responsive slicing of multidimensional (up to 4D) DataArray objects, including Dask-backed data.

• Unlimited number of cursors with independent binning and code export for each line cut.

• Rich colormap controls with power law scaling, midpoint-aware scaling, and live color range adjustment.

• Built-in menus for rotation, symmetrization, averaging, cropping, coordinate reassignment, Fermi edge correction, and other common operations.

• Tight integration with common analysis helper tools such as ktool, dtool, and other tools listed in Other interactive tools, all accessible from ImageTool’s menus and context menus.

• Seamless integration with ImageTool manager when you need to organize many windows, share workspaces, or synchronize with Jupyter notebooks.

Launching ImageTool

ImageTool expects image-like data—usually a DataArray—with 2–4 dimensions. ImageTool tries to handle incompatible input dimensions by adding a new dimension for 1D data and squeezing out dimensions of size 1 for 5D+ data. Non-uniform coordinates gain parallel _idx indices so you can still slice by position. Supported inputs include numpy arrays, Dataset, or entire DataTree objects; Dataset and DataTree inputs open one ImageTool window per valid variable.

Entry points

• Use the xarray.DataArray.qshow() accessor on your data:

  data.qshow(link=True)
  

• Call erlab.interactive.imagetool.itool() directly:

  import erlab.interactive as eri
  
  eri.itool(data, cmap="cividis")
  

  Passing a list or dataset to itool spawns multiple windows; set link=True to synchronize their cursor positions and bins.

• Launch ImageTool from IPython or a notebook using the %itool line magic. Load the extension first:

  %load_ext erlab.interactive
  

  Then run:

  %itool data
  

  where data is a variable in the current namespace. You can pass additional flags, such as -m or --manager which sends the window straight to the manager. Type %itool --help or %itool? to list all supported flags.

• Need to open a file quickly? Use File → Open… inside ImageTool. The dialog lists every available loader, including those from data loader plugins, so you can switch between formats without writing code.

• If you are using VS Code, you can open a DataArray in ImageTool directly from the GUI with the erlab extension ( marketplace | open-vsx ).

Notebook auto-loading

Add erlab.interactive to your IPython configuration so %itool is ready whenever a notebook starts.

Tip

If you use VS Code with the Jupyter extension, add this to your workspace or user settings.json:

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

To integrate ImageTool windows with notebook variables—including bi-directional updates—switch to the ImageTool manager and use the %watch magic described in Notebook integration.

Round-trip

Start from Python with xarray.DataArray.qshow(), erlab.interactive.imagetool.itool(), or %itool, then use Copy selection code or dialog Copy Code to move the chosen selection or transform back into a notebook. If edits should update a live notebook variable instead of the clipboard, move the window to the manager and use %watch.

The full GUI/API mapping lives in Operation map.

Interface tour

Every ImageTool window is built from an ImageSlicerArea plus dockable control panels:

• Main image and cross-sections – The central plot renders the current 2D slice. Orthogonal slices and cursor readouts update in real time as you move the cursors.

• Cursor panel – Add, remove, and modify cursors here. The coordinates of the active cursor are shown in editable text boxes.

• Color panel – Manipulate colormap normalization and appearance.

• Binning panel – Set bin widths per dimension and reset them with . Changes to the bin widths you make while is toggled are applied to all cursors.

Working with dimensions and coordinates

• The order of dimensions can be swapped using the arrow buttons in the cursor panel. The direction of the arrow intuitively indicates which slice will be swapped with the main view.

• Non-uniform coordinates are converted with a _idx suffix for plotting. Their true values are displayed in the cursor readouts.

• Use Edit → Edit Coordinates to open the Coordinate Editor dialog. This is just a GUI for xarray.DataArray.assign_coords() that lets you specify start/end values or per-point overrides.

• Dask-backed arrays are fully supported. The dedicated Dask menu exposes actions to compute the array into memory, rechunk automatically, or choose custom chunk shapes within ImageTool.

• Overlay plots of non-dimensional coordinates (e.g., temperature) on the data from View → Plot Associated Coordinates.

Slicing, binning, and linking

• Drag with the left mouse button to pan and with the right mouse button (or the wheel) to zoom. Scroll on individual axes to zoom along a single dimension.

• To change the slicing position, drag on a cursor line to move it, or drag on the plots while holding Ctrl. You can also use the keyboard shortcuts listed in the View → Cursor Control submenu which allow precise nudging of the active cursor with arrow keys.

• When binning is enabled, the data shown are an average over the specified bin widths, which are indicated by shaded regions near the cursor lines.

• When comparing data in several ImageTool windows, you can link them either at creation (eri.itool([data1, data2], link=True)) or inside the manager. Linked windows maintain synchronized slicing positions, bin widths, and cursor counts.

Cursor control and context menus

• Hover over any toolbar icon to see a short description of its function.

• Copy the numeric readouts at any time with Ctrl+Shift+C (cursor values) or Ctrl+Alt+C (cursor indices). ImageTool copies native Python literals so you can paste them directly into scripts.

• Multiple cursors can be added to the image using the button in the cursor panel. They can each be dragged independently, and their bin widths can be set separately in the binning panel. To switch the active cursor, simply click on it or select it from dropdown menu in the cursor panel.

• To move all cursors simultaneously, hold Alt while dragging a cursor line, or use Ctrl+Alt while dragging on the image.

• Right-click on an image plot or line plot to open a useful context menu. Common options include copying the slicing code, locking the aspect ratio on image plots, exporting the current selection, and opening helper tools.

  On image plots, the context menu can launch goldtool, restool, dtool, and ftool. On line plots, the context menu offers ftool.

  Hint

  Holding Alt while opening the menu switches many actions to cropped mode, which crops the data to what is currently visible in the plot before performing the action. This is useful for conducting analysis on a specific region.

• Use Edit → Rotation Guidelines to add quick measurement aids. The guideline angles feed directly into the Rotate dialog so you can align your sample quickly.

• Use View → Open ktool and View → Open meshtool for the helper tools launched from the main menu rather than the plot context menu.

• The default color cycle of cursors is user configurable. See Configuration.

• Colors can be changed individually from View → Edit Cursor Colors…, where you can choose from a colormap or edit each cursor’s color separately.

• Alternatively, the colors of the cursors can be set to follow a specific coordinate dynamically based on their positions. This can be enabled from View → Set Cursor Colors by Coordinate….

Color and normalization

• Toggle to lock the color range to the global data min/max and display a colorbar alongside the image. Drag on the colorbar to update limits interactively or right-click to type exact bounds.

• applies gamma scaling relative to the midpoint, which is handy for centered intensity scales such as spin-polarized or dichroic data.

• Use to flip between normalization behaviors of matplotlib.colors.PowerNorm and erlab.plotting.colors.InversePowerNorm.

• By default, only a subset of Matplotlib colormaps is loaded. You can load the whole catalog by right-clicking on the colormap drop-down and selecting Load All Colormaps.

Editing and filtering data

Editing dialogs live under the Edit and View menus. Most transforms are destructive yet provide an Open in New Window checkbox so you can keep the original data. When Copy Code is available, the generated snippet is placed on your clipboard, ready to paste into a script or notebook for reproducibility.

• Edit → Rotate opens the Rotate dialog. Enter the angle, center, interpolation order, and whether to reshape the image. If a rotation guideline is active, the dialog pre-fills the matching angle and pivot.

• Edit → Average opens the Average Over Dimensions dialog. Select any set of dimensions to average via xarray.DataArray.qsel.average().

• Edit → Symmetrize opens the Symmetrize dialog. Mirror a selected dimension about a specified center with additive or subtractive symmetry, valid or full overlap, and one-sided or two-sided output.

• Edit → Crop opens the Crop Between Cursors dialog, while Edit → Crop to View opens the Crop to View dialog.

• Edit → Correct With Edge… opens the Edge Correction dialog. If your data exposes an eV axis, ImageTool can import a previously fitted edge via xarray_lmfit.load_fit() and shift the spectrum accordingly.

• View → Normalize opens the Normalize dialog, a non-destructive filter that supports area normalization, min-max scaling, and baseline subtraction.

• Edit → Edit Coordinates opens the Coordinate Editor dialog for precise coordinate reassignment, including non-uniform axes.

Use Edit → Undo and Edit → Redo to walk changes back, and View → Reset to remove any currently applied filter function. ImageTool also keeps track of additional helper windows opened from the context menus, so everything is closed cleanly when the main window exits.

Regions of Interest (ROIs)

ROIs let you focus on a sub-region of the data. They can be created and manipulated directly on the image plot.

Only polygonal ROIs with arbitrary vertex counts are supported at this time.

Create and manipulate

• Right-click on an image plot and choose Add Polygon ROI. A two-point line appears near the active cursor so you can immediately drag it into place.

• Drag any handle to move a vertex. Click on a segment to insert a new vertex.

• Right-click on a ROI and pick Edit ROI… to open a tabular editor.

  • The coordinate table lists every vertex of the ROI.

  • Check the Closed option to convert an open polyline into a filled polygon.

• Edits are logged, so you can undo accidental drags with Ctrl+Z.

ROI-driven analysis

Two additional context-menu actions appear upon right-clicking on a ROI:

• Slice Along ROI Path interpolates the data with erlab.analysis.interpolate.slice_along_path().

  Choose a step size and a name for the new path dimension, then decide whether to open the result in a new window or replace the current data.

• Mask Data with ROI calls erlab.analysis.mask.mask_with_polygon() to mask the data with the ROI.

  You can choose whether to invert the mask and whether to trim the resulting data.

Note that both procedures work on the entire data volume, not just the visible slice.

Python equivalent

ImageTool is the GUI counterpart to the core selection and transform APIs: .sel(...), .isel(...), xarray.DataArray.qsel.average(), erlab.analysis.transform.rotate(), erlab.analysis.transform.symmetrize(), xarray.DataArray.assign_coords(), erlab.analysis.interpolate.slice_along_path(), and erlab.analysis.mask.mask_with_polygon().

Use the tool to discover parameters quickly, then keep the exact public API call in Python. See Operation map for the maintained crosswalk.

Exporting and settings

• File → Save As… exports the current data to NetCDF or HDF5.

• File → Move to Manager hands the window off to the ImageTool manager.

• File → Settings opens the shared settings dialog described in Configuration.

Keyboard shortcuts

Most actions advertise their shortcut directly in the menu bar. The table below highlights common gestures. Replace Ctrl with ⌘ and Alt with ⌥ on macOS.

Shortcut	Description
LMB Drag	Pan
RMB Drag	Zoom and scale
Ctrl+LMB Drag	Move active cursor
Ctrl+Alt+LMB Drag	Move all cursors simultaneously
Alt while dragging a cursor line	Move all cursor lines along

Rule of thumb: hold Alt to apply actions to all cursors. Shortcuts for ‘shifting’ a cursor involves the Shift key.