Python integration¶

Use these guides to open Python data in ImageTool and move data or operations between Python, ImageTool, and Manager. Read Python and GUI workflows to understand when to move an operation between the two environments.

Opening Python data in ImageTool¶

Call ImageTool with the DataArray from the current Python session:

import erlab.interactive as eri

eri.itool(data)

Pass a list and set link=True when several arrays must open with synchronized cursors and bins. If the input has more than four effective dimensions, select or aggregate dimensions in Reduce Dimensions to Open before opening the result.

See Opening ImageTool for all Python, IPython, and VS Code entry points. Use Synchronizing a notebook variable with ImageTool when changes must stay synchronized in both directions.

Loading ImageTool commands when a VS Code notebook starts¶

Use this task for notebooks that run in VS Code with the Jupyter extension.

Open the VS Code user or workspace settings.json file.

Add this setting:

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

Restart the notebook kernel.
Run %itool --help to confirm that the extension loaded.

This setting applies only to notebooks that VS Code starts. In another notebook frontend, run %load_ext erlab.interactive in the notebook unless that frontend has an equivalent startup-command setting.

Continuing an ImageTool operation in Python¶

Open Python data with xarray.DataArray.qshow(), erlab.interactive.imagetool.itool(), or %itool.
Make the required selection or transformation in ImageTool.
Choose Copy selection code from a plot or Copy Code from the operation dialog.
Paste and run the copied expression in the notebook.

When ImageTool is managed, select the result row and use Copy Full Code to include the recorded input and preceding operations. Inspect file paths, variable names, and parameter values before running copied code.

Use Synchronizing a notebook variable with ImageTool instead when the ImageTool result must update a live notebook variable. See Operation map for the corresponding Python operations.

Synchronizing a notebook variable with ImageTool¶

Load the IPython extension and start a watch:

%load_ext erlab.interactive
%watch my_data

The Manager creates or reconnects an ImageTool row labeled my_data. Reassigning a DataArray to my_data updates the row after the notebook cell finishes. Compatible ImageTool edits update the notebook variable.

Run %watch my_data again to force a refresh. To stop synchronization but keep the ImageTool row, run:

%watch -d my_data

Use %watch -x my_data when the row must also close. See Notebook synchronization commands for all %watch forms.

If the variable is deleted or replaced by an object that is not a DataArray, the Manager breaks the watch and keeps a regular ImageTool row.

Reconnecting variables after restarting¶

Open the saved Manager workspace.
Run the notebook cells that recreate the watched DataArray variables.
Reconnect all matching names:
```
%watch --restore
```

Rows with missing variables or variables that are not DataArray objects remain disconnected. If several rows use the same variable name, remove the unwanted watch before reconnecting so the Manager does not have to guess.

When sharing the workflow, send both the notebook and .itws workspace. The files do not need to be in the same directory, but the notebook must recreate the variable names stored in the workspace.

Using a non-IPython environment¶

Call the Python API with the namespace that contains the variable:

from erlab.interactive.imagetool.manager import watch

watch("my_data", namespace=globals(), poll_interval_s=0.5)

Use watch as watch("my_data", stop=True) to stop one watch. Use watch(stop_all=True) to stop all watches. Use watch(restore=True) to reconnect rows from the open workspace.

Provide namespace= when caller scope is not obvious, such as inside a helper or callback. Use shutdown before the host application exits.

Use Loading ImageTool commands when a VS Code notebook starts to load %watch automatically in notebooks.

Copying Manager data into Python¶

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.

Use the row index shown by the Manager. When several Manager windows are running, select the target Manager first as described in Sending data to a specific Manager window.

Transferring Manager data between notebooks¶

Use IPython %store when data in one Manager session must be available to another notebook kernel. The Manager console and the receiving kernel must use the same IPython profile. They must also run as the same operating-system user.

Select the required ImageTool rows in the Manager.
Choose File ‣ Store with IPython or the matching row context-menu action.
Record the variable names used by the Manager.
In the receiving notebook, restore each variable:
```
%store -r my_data
```
Confirm that the restored object is a DataArray:
```
import xarray as xr

isinstance(my_data, xr.DataArray)
```
The result must be True before you continue the analysis.

The restored DataArray is independent of the live Manager row. Use Synchronizing a notebook variable with ImageTool instead when changes must remain synchronized in both directions.

If %store cannot find the variable or the restored object is not a DataArray, use a file instead. Different IPython profiles can cause this problem. Save the ImageTool data as NetCDF or HDF5 with Saving ImageTool data to a file. Then load the file in the receiving notebook:

import xarray as xr

my_data = xr.load_dataarray("my-data.h5", engine="h5netcdf")

Use the saved .nc path instead when you selected NetCDF. Inspect the restored dimensions, coordinates, and attributes before you continue.

Sending data to a specific Manager window¶

Multiple ImageTool Manager windows can run at the same time. The first live window has index 0. Later windows receive 0-based indexes in their start order.

Start the required Manager windows.
Inspect the live windows from the Python process that contains the data:
```
import erlab.interactive.imagetool.manager as itm

itm.managers
```
Send the data with the index shown for the target Manager:
```
itm.managers[1].show(data)
```
Confirm that the new ImageTool row appears in the target Manager.

If more than one manager is running and no default has been selected, calls that use manager=True raise an error instead of guessing. See Manager selection for default selection, explicit target arguments, and IPython magic forms.